Cream of the Crop 12

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 12 / Cream of the Crop 12 (Part II) / Cream of the Crop 12 (Part II).iso / OS2 / MAG9DEMO.ZIP / MAGDOC.ZIP / MAGNUM.DOC

Wrap

Text File | 1996-04-01 | 799.9 KB | 20,794 lines

Gilmore Systems "MAGNUM BBS (r) SYSTEM FOR OS/2" Version 9.00, April 1996 (C)Copyright Gilmore Systems - 1989, 1996 - All rights reserved - Gilmore Systems 7354 Rubio Ave. Van Nuys, CA 91406 - USA Voice: (818) 782-1870 FAX: (818) 782-2093 BBS: (818) 782-6290 E-mail: postmaster@gilmore.com First Printing: September, 1989 This Printing: April, 1996 All programs and documentation written by: Chuck B. Gilmore Gilmore Systems (C)Copyright Gilmore Systems, 1989, 1996 - All Rights Reserved No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Gilmore Systems. Disclaimer Gilmore Systems makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Gilmore Systems reserves the right to revise this publication and to make changes from time to time in the content hereof without obligation of Gilmore Systems to notify any such person of such revision or changes. Under no circumstances will Gilmore Systems or the author be held responsible for any consequential or inconsequential damages resulting from the use or misuse of any furnished programs or documentation. Artic is a trademark of IBM Digiboard is a trademark of Digiboard Corp. Hayes is a trademark of Hayes Computer Products IBM is a trademark of International Business Machines, Inc. Intel is a trademark of Intel Corporation Magnum BBS is a trademark of Gilmore Systems Microsoft is a trademark of Microsoft Corporation. MultiTech is a trademark of Multi Tech Systems OS/2 is a trademark of IBM and Microsoft US Robotics and HST are trademarks of US Robotics LICENSE AGREEMENT FOR "MAGNUM BBS" (r) FOR OS/2 IMPORTANT: READ THE FRONT AND BACK OF THIS PAGE BEFORE USING THE DISKS. BY OPENING THE DISK PACKAGING YOU SHOW YOUR AGREEMENT TO THE TERMS OF THIS LICENSE! REFUND: If you choose not to accept the terms of this license agreement, you may obtain a full refund by returning this package to Gilmore Systems within three (3) days, provided you have not opened the envelope containing the program disk(s). DEFINITIONS: The term "Software" as used in this agreement means the full system and all utility computer programs contained on the disks in this package, including any updates subsequently supplied by Gilmore Systems. "Software Copies" refers to the actual copies of all or any portion of the software, including back-ups, updates, merged or partial copies permitted hereunder or subsequently supplied by Gilmore Systems. "Related Materials" refers to all printed materials provided in this package or later supplied by Gilmore Systems for use with the Software. USES NOT PERMITTED: You may not: Make copies of the Software, except as permitted below. Make copies of the Related Materials. Rent, lease, sub-license, or transfer the Software, Software Copies, Related Materials or your rights under this license. Alter, reverse-engineer, disassemble or decompile the Software. Remove or obscure the Gilmore Systems copyright or trademark notices. PERMITTED USES: You may: Install the Software on a permanent storage device (hard disk drive) Make one working copy of the Software Program. If the working copy will no longer work properly, the Licensee may make another working copy of the Software Program but only if the inoperable working copy is first destroyed. In addition, all the information appearing on the original disk labels (including the copyright notice) must be copied onto the working copy labels. Use the Software on a single computer or on a single workstation on a network. Additional workstations utilizing the Software must be licensed by Gilmore Systems. The network version may be used on multiple computers that are connected by direct cable to the same network server. This license gives you certain limited rights to use the Software. You do not become an owner of the Software, and Gilmore Systems retains title to all the Software, Software Copies and Related Materials. Additionally, you agree to use reasonable efforts to protect the Software from unauthorized use, reproduction, distribution or publication. All rights not specifically granted in this license are reserved by Gilmore Systems. DURATION: This agreement is effective from the time you open the sealed disk package. Your license continues for twenty-five (25) years or until you return the original disks and any backup copies to Gilmore Systems, whichever comes first. If you breach this agreement, Gilmore Systems can terminate this license by notifying you in writing. You will be required to return all Software, Software Copies, and Related Materials to Gilmore Systems. We can also enforce our other legal rights. GENERAL: This agreement represents our entire understanding and agreement regarding the Software, Software Copies and Related Materials and supersedes any prior purchase order, communications, advertising or representations. This license may only be modified in a written ammendment signed by an authorized Gilmore Systems officer. If any provision of this agreement shall be unlawful, void or unenforceable for any reason, it shall be deemed severable from, and shall in no way affect the validity or enforceability of the remaining provisions of this agreement. This agreement shall be governed by California law. You acknowledge that you have read every provision of this contract. By opening the disk packaging, you acknowledge that you have read and agree to this contract. LIMITATIONS: Gilmore Systems warrants to the original licensee that the original program disk(s) housing the Software is free from defects in materials and workmanship under normal use and service for a period of ninety (90) days from the date of purchase. Gilmore System's entire liability and your exclusive remedy shall be replacement of the disk(s) not meeting this Limited Warranty if returned to Gilmore Systems during the 90 day period. Except for the foregoing, this product is provided "as is" without any warranty of any kind. The entire risk as to the results and performance of the program is assumed by you. Gilmore Systems does not warrant, guarantee, or make any representations regarding the use of, results of, merchantability or fitness for a particular use of the product. Should the program prove defective, you (and not Gilmore Systems) assume the entire cost of all necessary servicing, repair or correction. Further, Gilmore Systems does not warrant, guarantee, or make any representations regarding the use of, or the results of the use of the program in terms of correctness, accuracy, reliability, currentness, or otherwise; and you rely on the program and results solely at your own risk. Gilmore Systems will not be liable for any damages, including but not limited to system damage, service, repair, correction, loss of profit, lost savings, or any other incidental, consequential, or special damages of any nature whatsoever resulting from the use or misuse of this product, or the inability to use this product. Table of Contents Page 1 TABLE OF CONTENTS Table of Contents ........................................................ 1 MAGNUM BBS (r) system for OS/2 ......................................... 1-1 Getting Started ................................................... 1-2 Optional add-on modules available from Gilmore Systems ............ 1-3 Configuring MAGNUM ==> start here <== ............................. 1-4 Configuring MAGNUM ................................................ 1-5 Compiling your STARTUP.n file(s) ................................. 1-34 The MODEL statement .............................................. 1-35 SPECIAL.n files: Detecting Error-Correction, FAX callers, etc .... 1-36 Directory Structure of MAGNUM .......................................... 2-1 PROGRAM DIRECTORY (PGM_DIR) ....................................... 2-2 SESSION_DIRECTORY (SES_DIR) ....................................... 2-4 BULLETIN, MENU, HELP Directories (BUL_DIR, MNU_DIR, HLP_DIR) ...... 2-9 DISPLAY DIRECTORY (DSP_DIR) ...................................... 2-10 EXTERNAL DIRECTORY (EXT_DIR) ..................................... 2-12 RJE DIRECTORY (RJE_DIR) .......................................... 2-14 MSG,WORK,USER,SYSOUT Dirs (MSG_DIR,WORK_DIR,USER_DIR,SYSOUT) ..... 2-15 Order of Display Files ........................................... 2-17 Running MAGNUM BBS ..................................................... 3-1 Starting MAGNUM BBS for the First Time ............................ 3-2 Starting Your FILES Database ...................................... 3-4 The MAGFILE.EXE Program (bulk file add) ........................... 3-5 The MAGDRIVE.EXE Program (CD-ROM Support) ......................... 3-7 Customizing MAGNUM - Display Files/MILC Commands ....................... 4-1 Intro ............................................................. 4-2 Color Commands (@A) ............................................... 4-3 Branch (IF) Commands (@B) ......................................... 4-4 Screen Control Commands (@C) ...................................... 4-6 Date Conversion Function (@D) .................................... 4-10 External and RJE Program Execution Commands (@E) ................. 4-12 Miscellaneous @E commands ........................................ 4-15 Additional @E commands for 'Extended FileBase and MsgBase' ....... 4-18 Include File Commands (@I) ....................................... 4-19 Date Manipulation Commands (@J and @Y) ........................... 4-21 Call Command (@K) ................................................ 4-22 Security Level Commands (@L) ..................................... 4-23 Match Filename in FILE DATAbase (@M) command ..................... 4-24 Numeric (@N) Commands (ie: mathematics, I/O, etc) ................ 4-25 Other (Miscellaneous) Commands (@O) .............................. 4-30 Position (Label) Commands (@P) ................................... 4-33 Retain (@R), File (@F) and Query (@Q) MILC Variables @Z & @N ..... 4-34 Stack Keystrokes Command (@S) .................................... 4-36 Text to Log (activity) File (@T) ................................. 4-37 User Substitution Commands (@U) .................................. 4-38 View System Variables (@V) ....................................... 4-42 Wait Command (@W) ................................................ 4-44 String (@Z) Commands (ie: String Logic, I/O, etc) ................ 4-45 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 2 Table of Contents Character Display - @\ command. .................................. 4-49 "Sysop Only" MILC commands: @$x, @&x, @!x, and @?x ............... 4-50 Advanced MILC Command Usage - Indirect Addressing ................ 4-52 Advanced MILC Command Usage - Enhanced Indirect Addressing ....... 4-54 MAGNUM's Sysop Console ................................................. 5-1 Intro ............................................................. 5-2 The Bell, Forceoff, Switch and Info Commands ...................... 5-3 The "* auto" and "* noauto" commands .............................. 5-5 The level, print and lockout commands ............................. 5-6 The active, time, announce/normal, and logon commands ............. 5-7 The endnow, end, shutdown and msg commands ........................ 5-9 miscellaneous commands ........................................... 5-11 CHATting between SYSOP (you) and a USER via the Console .......... 5-17 Displaying a File with <F6> ...................................... 5-18 TEST Mode (Testing your modem) ................................... 5-19 Icon Control Commands ............................................ 5-20 Program Control Commands ......................................... 5-21 Back to Display Files & Subdirectories ................................. 6-1 The PROGRAM DIRECTORY ............................................. 6-2 The SESSION DIRECTORY ............................................. 6-4 The BULLETIN DIRECTORY ........................................... 6-11 The MENU DIRECTORY ............................................... 6-12 The HELP DIRECTORY ............................................... 6-13 The DISPLAY DIRECTORY ............................................ 6-14 The EXTERNAL DIRECTORY ........................................... 6-16 The RJE DIRECTORY ................................................ 6-17 The MESSAGE SUBDIRECTORY ......................................... 6-18 The WORK SUBDIRECTORY ............................................ 6-19 The SYSOUT SUBDIRECTORY .......................................... 6-20 The USER SUBDIRECTORY ............................................ 6-21 Using Magnum BBS as a USER ............................................. 7-1 Handles (Alias Names) ............................................. 7-3 The MAIN MENU ..................................................... 7-4 The MESSAGE MENU ................................................. 7-11 The FILES MENU ................................................... 7-18 The SYSOP MENU ................................................... 7-30 The RJE MENU ..................................................... 7-41 Magnum's ACE (Automatic Command Execution) Event Handler ............... 8-1 Advanced ACE Usage ................................................ 8-6 The MBBSEXEC Sysop Maintenance Utility Program ......................... 9-1 MBBSEXEC Field Names .............................................. 9-5 Field Names for the USER Database ................................. 9-6 Field Names for the MSG Database .................................. 9-9 Field Names for the FILE Database ................................ 9-10 Field Names for the RJE Database ................................. 9-12 Field Names for the UTILIZ Database .............................. 9-13 Syntax and Construction of an MBBSEXEC program ................... 9-14 The Assignment Statement ......................................... 9-16 Comparison Statements (IF) ....................................... 9-17 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Table of Contents Page 3 Branch Statements (GOTO) ......................................... 9-18 Date Fields are Special Cases .................................... 9-20 Mathematics ...................................................... 9-21 Processing a Single User Instead of the Entire Database .......... 9-22 MBBSEXEC 'Simple' Summary ........................................ 9-25 MBBSEXEC Advanced Features ....................................... 9-29 MBBSEXEC Advanced Features - the EXIT statement .................. 9-30 MBBSEXEC Advanced Features - Special Fields in USER database ... 9-31 MBBSEXEC Advanced Features - #LOG_FILE: .......................... 9-32 MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters ... 9-33 MBBSEXEC Advanced Features - Strings, Binary & Console Output .... 9-37 MBBSEXEC Advanced Features - the INPUT() statement ............... 9-39 MBBSEXEC Advanced Features - the WHILE() statement ............... 9-40 MBBSEXEC Advanced Features - The } ELSE { statement .............. 9-41 MBBSEXEC Advanced Features - Indirect Addressing (Indexing) ...... 9-43 MBBSEXEC Advanced Features - Equating names for @TALLY/@STRING ... 9-45 MBBSEXEC Advanced Features -Writing/calling your own functions ... 9-46 MBBSEXEC Advanced Features -Setting the NEXT record to Process ... 9-49 MBBSEXEC Advanced Features - Executing an External Program ....... 9-50 MBBSEXEC Advanced Features-Save/Restore/Start/Delete Pgm Data .... 9-51 MBBSEXEC Advanced Features-The EXTRACT() function ................ 9-54 MBBSEXEC Advanced Features - Sample .MEX Programs ................ 9-56 MBBSEXEC -- Program Summary (All Sections) ....................... 9-59 Magnum Utility Programs ............................................... 10-1 MAGFUTIL.EXE (A Very Powerful File Maintenance Utility) .......... 10-2 Supplied External and RJE Programs with Magnum BBS .................... 11-1 The NotePad Facility .................................................. 12-1 Setting up Additional Copies of Magnum on your LAN .................... 13-1 Remapping Directories for your Workstation ....................... 13-3 For Systems using 'Extended File' and/or 'Extended MsgBase' ........... 14-1 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) ........................... 15-1 Outside Mail .......................................................... 16-1 The QWK Message format: Offline Messaging, QWK 'Networking' ...... 16-2 The "Outside Mail" ID ............................................ 16-3 Internet E-mail ....................................................... 17-1 General Info and Setup ........................................... 17-2 EMAILIN.EXE parameters ........................................... 17-7 General and Closing Remarks ........................................... 18-1 General Remarks .................................................. 18-2 Closing Remarks .................................................. 18-3 Index .................................................................. I-1 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank MAGNUM BBS (r) system for OS/2 Page 1-1 Getting Started Rather than waste time with the standard commentary of copying files and creating directories, we'll assume you know what you're doing since a working knowledge of OS/2 and it's directory structure is needed. A semi-automated installation program is included which will create install Magnum for you using the (intelligent) defaults built into it. What You Need You'll need an IBM or compatible computer capable of running OS/2 version 1.2 or above, OS/2 version 2.0 or above, or OS/2 version 3.0 (Warp) or above. The most reliable versions of OS/2 (as of this writing) are versions 1.3, 2.1 and 3.0. Computers utilizing the Intel 8088, 8086 and 80186 microprocessors are not capable of running the OS/2 operating system. Computers utilizing the Intel 80286 microprocessors can run OS/2 version 1.x but not 2.x. Computers utilizing the Intel 80386, 80486 or Pentium microprocessor can run any version of OS/2. OS/2 runs in proctected mode on computers utilizing the Intel 80286, 80386 or 80486 microprocessor. You'll need approximately 5 Mb RAM for the operating system plus 1 node, 500K RAM for each additional node (these estimates are purposely high, you will probably need less). You will also need a modem for each node (your modem and cable must support CTS and RTS hardware handshaking, and must be capable of responding to the DTR signal). You will also need a text editor to configure Magnum's STARTUP files. OS/2 version 1.2 is the minimum operating system requirement for Magnum, however, we recommend using OS/2 version 1.3, 2.1, or 3.0 (Warp). It doesn't matter if you're running SE or EE (OS/2 1.x) or Extended Services (OS/2 2.x). NOTES The version you have of MAGNUM BBS is a multi-node version (even the 2-node version (1 dialup) is multi-node in that a remote user plus the sysop at the console can be online simultaneously). It can run with one or more nodes. IBM PS/2's can address COM1 thru COM3 with OS/2 1.x, or COM1 thru COM4 with OS/2 2.x. Non-PS/2's can only address COM1 and COM2. If you're using a version of Magnum that supports more serial ports than the operating system, you will need IBM's Artic communications coprocessor card and Quadron Service Corp's OS/2 comm device driver software (QCOM) to access the comports beyond COM2 (non-PS/2) or COM3 or COM4 (PS/2). Digiboard also supplies a communications coprocessor card and OS/2 device driver software. Both the Artic and Digiboard cards are available for AT and MicroChannel machines. If you're using OS/2 2.x, the com device drivers supplied with the operating system are not very good and can cause unexpected problems. We recommend using Ray Gwinn's com drivers which can be downloaded from our BBS (the filename is SIOxxx.ZIP where xxx is the current version number - details are on our BBS). Ray's drivers will support up to 16 serial ports. The version number on your Magnum distribution diskette reveals how many nodes you have. If your version number is 9.00C5, the 5 after the C MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-2 MAGNUM BBS (r) system for OS/2 Getting Started means you have 5 nodes, node 5 being your local (console) node. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-3 Optional add-on modules available from Gilmore Systems Additional Incoming DIAL-UP Lines via LAN The version you have is "LAN ready". You can purchase and set up additional copies of Magnum BBS to be run on other workstations to provide dial-up (modem) support and share the databases with the main BBS (server). Installing the same copy of Magnum BBS at other workstations will not work (each workstation requires its own serialized copy of Magnum BBS software). If you're installing more than one copy of Magnum BBS for your network, make sure your PROGRAM DIRectory, SYSOUT DIRectory, and WORK DIRectories (described later in this chapter) are unique for each workstation. Contact Gilmore Systems for pricing information relating to additional workstations. Additional Incoming LOCAL (modemless) Lines via LAN Pipe Modules The version you have is "LAN ready". With the purchase of our optional Pipe Modules, you can log onto Magnum BBS from OS/2 or DOS workstations. IBM's LAN Server, Microsof'ts LAN Manager, Banyan Vines, or any other LAN software supporting "named pipes" will work with our pipe modules. With our pipe modules, any node(s) on your current BBS can be set up as a "pipe" node instead of a "modem" node to allow pipe access. Those logging on via "pipe", are treated as any remote modem caller, thus system security is maintained. Extended File and Message Bases Magnum BBS is supplied with the main MessageBase and FileBase (MsgBase 0 and FileBase 0) built in. Each FileBase has 26 file 'areas' (A-Z), and each MsgBase has 26 message conference 'areas' (A-Z). We offer both an 'Extended MessageBase' and an 'Extended FileBase' module which extends Magnum's capabilities. The 'Extended FileBase' module, extends Magnum's FileBase capabilities from 1 FileBase of 26 areas to up to 256 FileBases of 26 areas each for a total of 6,656 file 'areas'. The 'Extended MessageBase' module, extends Magnum's MessageBase capabilities from 1 MessageBase of 26 message conference areas to up to 256 MsgBases of 26 areas each for a total of 6,656 message conference 'areas'. CallBack Module For the ultimate in security, our optional CallBack module will allow Magnum to 'call back' your users after they log onto your system. It can be set up to provide 'mandatory' or 'courtesy' callback on an individual basis (only those users you specify in a 'callback list' will be considered for CallBack). Although CallBack will work fine on a node which is used for incoming calls, we strongly recommend dedicated CallBack node(s) depending on how much the callback facility will be used. In the event that all CallBack nodes are busy (in use), the CallBack module will queue up to 100 callers at a time for CallBack. Contact Gilmore Systems for pricing information on optional modules. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-4 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM ==> start here <== This document is a guide to help new Sysops through the confusion of setting up a new BBS. Since experience has shown that all new BBS sysops want to start running their new BBS program *yesterday*, we'll get right down to the business of system setup. Your hardware should enable you to run OS/2 version 1.2x, 1.3x, 2.xx or 3.xx (Warp). A safe memory requirement is 4-5 Mb just for the OS, 1 Mb for the parent process + 1 node, and 500K for each additional node you wish to run. To get started, insert the Magnum distribution diskette in Drive A: or drive B: (we'll assume drive A:). Next, enter the following command at an OS/2 command-line prompt: A:\MAGINST This will invoke the Magnum "Intelligent Installation" program. It will install Magnum for you on your hard disk with a minimal amount of questions. After the program completes, you'll be able to log onto your own "Magnum BBS" system via the console node. Additional configuration and modem (dial-up) configuration can be completed later at your convenience. ------------------------------------------------------------- NOTE: There are 10 Magnum configurations: 2-node, 3-node, 4-node, 5-node, 9-node, 13-node and 17-node, 25-node, 33-node and a 2-node DEMO (number of dialups = nodes-1). This manual assumes you are using the 4-node version (the most popular). The highest node number (2 for 2-node, 4 for 4-node, etc), is the LOCAL (console) node. -> Since this document assumes 4-node version, ANY reference in <- -> this document to node 4 should be replaced with your high <- -> node (2, 4, 9, for example). <- ------------------------------------------------------------- After you've run MAGINST.EXE and the program completes, follow the directions on the screen to start the BBS. If you start the BBS from a full-screen OS/2 command prompt, the BBS will run in full-screen mode. If you start from an OS/2 command "window", the BBS will run in text window. We recommend running it in a window so that you'll be able to monitor it from your desktop rather than having to switch to the full-screen session. If you'll be running in a text window, move the mouse pointer to the upper left corner, click once on the left button, and choose "maximize" (for now). You may also click on "font size" to adjust how much or how little space the window takes up on your screen. NOTE: Change your CONFIG.SYS file (usually in the root directory of your drive C) to append the paths that appeared on your scren at the end of the MAGINST.EXE program... you must REBOOT your system for MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-5 Configuring MAGNUM these changes to take effect. If you do not know how to do this, then switch to Magnum's PGM_DIR and run the command MAGPATH.CMD, but only run it ONCE! This will set the paths for the duration of your OS/2 command session. If you type EXIT to end the OS/2 command session, you'll need to run MAGPATH again prior to starting your BBS. It's much easier to append the permanent paths to your PATH statement in your CONFIG.SYS file. Once started, take note that there's a line on the screen that says "Command => ". To enter commands, start with either the * key or a digit. Enter the following command: * LOGON Follow it by pressing your ENTER key. Magnum will now start your local logon session using your console node. When logging on for the first time, enter your first name, optional middle name, and last name EXACTLY the way you responded to these prompts during the installation program. This first logon initializes the system. No name entry other than what matches that of the installation program will be accepted at this point. Once you've completed the new user logon procedure and are within the Main Menu, choose X to enter the Sysop Menu. Once in the Sysop menu, choose U for User Database area. Your user record should now be visible on your screen. Change your time_remaining and time_period fields to give yourself more time on the system (enter the full fieldname at the prompt, you will then be prompted for a new value to place in that field). >>>>>>>>>>>>>>>> The installation program has set up your local (console) node, and has set up your 1st dial-up node (node 1) for you identically. The installation program made your console node "active", and your node 1 "inactive" (for now). The installation program provided a "general setup" for you. The remainder of this chapter will guide you through more detail of setting up the system such that it matches your needs. First, make certain you are in your PGM_DIR. (ie: d:\MAGNUM\PGM_DIR where 'd:' is the drive letter that Magnum was installed on). Just like writing a program or a letter, you need a text editor to modify or create your configuration source files. You can have up to 4 configuration text files with MAGNUM (remember, this manual assumes the 4-node vesion... if you have the 17-node version for example, you can have up to 17 configuration files) with a filename format of STARTUP.X where X is the node you are defining. In other words, the file STARTUP.1 defines the node1 configuration, STARTUP.2 for node2, etc. STARTUP.4 (assume 4-node version) is not really a dial-in node, but the definition for the local (console) or virtual comport. The DEVICENAME for all STARTUP.x files except STARTUP.4 (local node) specifies which device is to be used for that node (ie: COM1, COM2, etc). Once you have modified the startup file(s) to your liking, you will need to MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-6 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM "compile" these configuration files with MAGNUM's BBS compiler - MAKEMBBS.EXE but that will be at a later point. In the meantime, lets discuss the configuration text file itself. The installation program already created STARTUP.1 and STARTUP.n (n is your console node: 4 in 4-node version, 13 in 13-node version, etc). To create a configuration file for another node, simply copy STARTUP.1 to STARTUP.x (x = new node to configure), edit the file and change the NODE: parm to match that of the node number, and change the WORK_DIR parm to be unique (and make sure you create that directory). We'll get into this more later on but for now lets start with the format of the STARTUP.x file(s) themselves. If you've already logged onto your BBS as above, please log off (if you've not done so already), and shut down your BBS by entering the command: * ENDNOW at the "Command => " prompt of the MBBS.EXE program (the same place you entered * LOGON). For simplicity's sake, lets assume you will set up your BBS with Node 1 for starters. You will need to get the file STARTUP.1 into your favorite text editor and begin modifying it. You'll only need to create STARTUP.x file(s) for the nodes you wish to have running at this time. IMPORTANT: > Although Magnum can be set up to work with your modem returning numeric or word result codes, numeric codes can be a time-consuming process to set up. For a speedy set up, where you needn't worry about result codes, have your modem return Verbose (word) results. Numeric result codes are returned when V0 appears anywhere in your modem init strings; Verbose (word) results are returned when V1 appears anywhere in your modem init strings. Some modems have a dip switch which may also need to be changed to match the type of result code (Numeric or Verbose) you wish. VERBOSE (V1) IS THE PREFERRED METHOD! > Make sure your modem responds to the DTR signal generated by the computer. Do NOT have the modem force the DTR signal high! > Make sure your modem is set to pass Xon/Xoff characters thru as data - Magnum will perform Xon/Xoff processing as needed. Starting at the top of the file (STARTUP.1) and working our way down, lets go through each of the parameters. All configuration commands are in the format of: KEYWORD: PARM ; Comment Simply, KEYWORD: is the name of the field you are defining, PARM is the value of the field, and the ; character starts a comment. A comment starting with the ; character remains a comment for the remainder of that text line. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-7 Configuring MAGNUM NOTE: The STARTUP.x file(s) are merely the human-readable form of your node configuration(s). These STARTUP.x file(s) must be "compiled" into MBBSINIT.x file(s) with the supplied MAKEMBBS.EXE program to convert them to a format that Magnum understands. More on this at the end of the this chapter, but first, the contents of the STARTUP.x file(s) will be explained. In order, here are the keywords and what they mean: ACTIVE - this keyword tells MAGNUM whether or not you want this node to be active. The acceptable parms are Y or N. If Y, then this node will become active when MAGNUM starts up. If N, MAGNUM will ignore this node and you are free to use the node for any other program such as a communications program (MagCom or TE/2 for example). Note that the installation program placed Y in this field for your console node, and N in this field for your STARTUP.1 file. If you wish to have node 1 active when you start Magnum (ie: normally COM1), supply Y to this field, otherwise N. MBBS_VERSION - this keyword will be used internally. You should leave this blank or accept the value already supplied. It will be automatically supplied when you "compile" the configuration. PARENT_SERNUM - this keyword expects a serial number for its parameter. If you're running a Magnum system on one machine and with no LAN (or LOCALBBS.EXE modules), then simply provide the serial number of your BBS system to this parm. However, in preparation for a higher degree of network support, this parameter must be the serial number of your MAIN BBS system ...if you're running more than one Magnum system (MBBS.EXE) on two or more different machines networked together, then supply the MAIN serial# as this parameter for EACH STARTUP.x files on all machines. This also applies to all STARTUP.x files for the local logon modules (LOCALBBS.EXE) running on your network. Once you decide which serial# is to be considered your MAIN system, NEVER CHANGE THIS PARM!! Encryption of passowrds and messages is based on this serial number, so all systems accessing your databases must share the same PARENT_SERNUM. ENCRYPT_MAIL - this keyword expects a parameter of Y or N (for 'yes' or 'no', respectively). If Y, then all messages entered on Magnum will be stored on disk in encrypted form. Magnum will automatically present the messages in readable form when being read by an authorized user. Because of the read/write access to subdirectories on networks containing Magnum messages (mail), encryption became necessary in order to preserve overall system security (ie: so that user's won't be able to write programs to MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-8 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM access the messages). Once you choose to activate message encryption, messages will be encrypted from that point on (or until you de-activate it). Messages entered without encryption (including all previous versions of Magnum) will remain unencrypted. If you use encryption for a while, then decide to change back to the non-encrypted fashion, the encrypted messages will remain encrypted (but will be transparent to you and your users). GEO_PRIVACY - this keyword expects a parameter of Y or N (for 'yes' or 'no', respectively). If Y, then Magnum will enforce Geographic Privacy by not allowing the user's geographic information to be displayed when: 1) Logging On (the "From City, State ? (Y/N) => " prompt supressed). 2) Will supress geographic information from main menu's "[U]ser Search". INACTIVITY_TIMER - this keyword expects a number in the range of 180 to 1800. This number will indicate the amount of time (in seconds) in which the system will automatically force a remote user off of the system due to inactivity. Prior to this version, 240 was hard-coded (4 minutes). Whatever number you choose, the system will issue a warning message to the remote user 60 seconds prior to the automatic logoff. NOTES: - For best results, supply a parameter which is a multiple of 60. - The inactivity timer applies once a user has actually logged onto the system. If the user has not responded the "Login" prompt within 3 minutes, the system will terminate the session. A user is considered to be logged on if one of the following is true: - The user is an existing user (in user database) and has properly entered their password. - The user is a NEW user (not in user database) and has completed the new user initial questions, at which time the "ID /xxx successfully added to user database" message appears. TRACK_UTILIZATION - this keyword expects a parameter of Y or N (for Yes or No, respectively). If the parameter is Y, utilization tracking for that node of your BBS will be stored in a utilization database file UTILIZ.DAT in the SESSION DIRectory associated with that node. Supply Y to the TRACK_UTILIZATION: keyword in all STARTUP.x files who's nodes you want tracked. Utilization tracking is stored as one record for each session (logon) that takes place for any node who's TRACK_UTILIZATION: parm is set to Y. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-9 Configuring MAGNUM MBBS_MODEM - this is where you supply a short (up to 25 characters) description of your modem. MBBS_COUNTRY - this is where you supply the name of your country (up to 20 characters). When new users log onto your system, this will be displayed to them as the default country when they are asked for their address information. DATEFORMAT - Supply a U for United States, or an E for European date formats. This is for reporting purposes - the date format your users choose is independent of this field. SERVERNAME - Optional. If you're using a LAN, supply the server name in this field, otherwise leave the field blank or don't supply the SERVERNAME: keyword at all. Although this field exists, it is not used by Magnum at this time. PRTY_CLASS - Optional. Allows you to change the priority class of a Magnum session. PRTY_CLASS can range from 0 to 4. 0 is generally not used since it indicates no change. 1 is the "Idle Time" class which is not recommended for BBS operation. 2 is the "Regular" class (the default). 3 is "time critical" which can seriously slow down all other sessions. 4 is the "Foreground" class. Unless you're familiar with multi-tasking time classes and priorities, we suggest you not supply this keyword or any parameters. NOTE: This keyword is intended for system administrators fine-tuning Magnum when used with the optional Pipe Modules. PRTY_LEVEL - Optional. Allows you to change the priority level within a class. PRTY_LEVEL can range from 0 to 31. 0 is the lowest level of a time class, while 31 is the highest level. The lower the number, the lower the amount of time OS/2 allocates to the program. Unless you're familiar with multi-tasking time classes and priority levels, we suggest you not supply this keyword or any parameters. The default will be level 0 for remote sessions, level 31 for console sessions. The default is 0 for the console node, 10 for all other nodes. NOTE: This keyword is intended for system administrators fine-tuning Magnum when used with the optional Pipe Modules. YMODEMG - Accepts a parameter of Y or N. If Y, Magnum will allow all users to be able to use the Ymodem-G protocol. If N, Magnum will only allow those with Error-Correcting modems (ie: MNP4, V.42, LAP, etc) to use Ymodem-G. Ymodem-G is a file transfer protocol that relies on an error-correcting modem to perform any error corrections. The nature of the protocol is to abort if the modem does not correct an error. If your modem is set up to return Numeric result codes, Magnum can ascertain whether the remote caller is using an error-correcting modem. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-10 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM If using Verbose (word) result codes, you can still ascertain whether its an error-correcting connection by creating the SPECIAL.n file(s) explained later. CMDIO - Optional. Value can range from 0 to 255. Refer to the definition of CHILDREN.BBS in chapter 2 and how to set the @N0 value for instructions on how to determine what the value should be. This value will be used to set how I/O is performed when CMD.EXE is run as a child of Magnum via the "[O]perating System/2" selection of the Sysop menu. If you leave out the CMDIO keyword, the default will be 5. VERBOSE_CONNECT - Optional. If you plan on using Verbose (word) result codes (V1 appears somewhere in one of your modem init init strings, and any related dip switches are set to insure verbose (word) results on your modem). Most modems return "CONNECT xxxxx" when a connection is made. Some modems, however, return "CARRIER xxxxx" for the baud rate of the connection (such as the Hayes V-series and Ultra, for example). Depending on which one your modem returns for baud rate connection, you'll need to supply one of the following: VERBOSE_CONNECT: CARRIER or VERBOSE_CONNECT: CONNECT If you omit this field, Magnum will take whichever the modem returns first (CARRIER or CONNECT) which may not reflect an accurate baudrate. For example, Hayes V-Series & Ultra return CONNECT xxxxx (where xxxxx is the DTE baudrate, the speed of Your computer to Your modem), and returns CARRIER xxxxx (where xxxxx is the DCE baudrate, the speed of Your modem to the Remote modem). ANNOUNCE_ONLY - the acceptable parms are Y or N. If Y, MAGNUM will treat this node as an announce-only node. If N, MAGNUM will treat this node as a regular BBS node. If announce only, it will answer the phone, display a file you create and hang up (See ANNOUNCE.x in chapter 2). NODE - although the extension of the filename (STARTUP.1 for example) indicates which node you are configuring, this parameter is mandatory and acts as a double check. (Note: In previous versions this used to be the COMPORT parm - please note the change). IMPORTANT: You must also have unique WORK DIRectories for each STARTUP.x file (described later on for keyword WORK_DIR). DEVICENAME - This parameter is the name of the device you'll be using MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-11 Configuring MAGNUM for the serial port of this node. Device names are usually COM1, COM2, etc but can be any other supported device (ie: the Octoport card uses device names of AUX0, AUX1, etc, Digiboard uses DIGI1, DIGI2, etc). This field accepts up to 30 characters. If you're running under a LAN (ie: Lan Server for example), you can supply the name of a redirected serial port. BAUDRATE - This parameter can range from 110 to 57600. The acceptable values are: 110, 150, 300, 600, 1200, 2400, 4800, 9600 and 19200, 38400 and 57600. This does not necessarily mean the modem's baud rate, but the speed with which the computer talks to your modem. Some modems such as the USRobotics HST Couriers and the Multitech to name a few, can communicate with the DTE (computer) at a much higher baud rate than the actual baud rate of the modem over the phone lines. NOTE: As of this writing, the COM0x.SYS device driver supplied with OS/2 1.x only supports a maximum of 19200. The COM.SYS device driver supplied with OS/2 2.1 supports up to 57600 baud with Magnum. If you're using a 3rd-party communications coprocessor such as IBM's Artic Card in conjunction with Quadron Service Corp's QCOM device driver, or if you're using the Digiboard communications coprocessor in conjunction with their OS/2 COM device driver software, you can supply a value of up to 57600 baud in this field. --> For those drivers supporting 115200 baud (115.2 KBaud), you may supply 1152 to indicate 115.2 KBaud - your parm MUST be supplied as 1152 (and NOT 115200 or 115.2). Quadron's driver for the Artic card, and Ray Gwinn's serial drivers support this baud rate. PARITY - for normal BBS communications, parity should be set to N (none). Other parms are E (even), O (odd), M (mark), S (space). DATABITS - for normal BBS communications, databits should be 8. Other choices are 7, 6 and 5. STOPBITS - for normal BBS communications, stopbits should be 1. Other choices are 1.5 and 2. WAITCARRIER - for normal communications, this should be 30, although the acceptable range is 1 to 255. This is the number of seconds Magnum waits for a result code from the modem once it's answered the phone. If no response within the time limit, it hangs up the phone and resets the modem for the next caller. NOTE: If your modem uses the "AT" command set, register S7 should match this parm. MODEMRESET - This is usually "AT Z" (without quotes). This is the string your modem requires for a reset. IMPORTANT: Some modems are MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-12 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM configurable as to wheter to reset from factory settings or NRAM. Set your modem to reset from NRAM. If your modem is not configurable and resets from factory settings, simply leave this field blank! If you're not sure, or things aren't resetting right, leave this field blank! THIS FIELD MAY OPTIONALLY BE BLANK. STARTUP1 - This is the initialization string for your modem. There are 3 initialization strings. Every modem is different, and even identical modems can have different startup strings. SEE THE FILE MODEMS.TXT ON YOUR MAGNUM DISTRIBUTION DISKETTE FOR SOME OF THE INITIALIZATION STRINGS FOR DIFFERENT MODEMS. Some older modems only accept 40-character strings. Others accept 80 characters. If you need more than this for your particular modem, that's the reason for the additional STARTUP2 and STARTUP3 fields - make sure you start each parm with AT if your modem uses the AT command set. THIS FIELD MAY OPTIONALLY BE BLANK. -> NOTE 1: In any of these strings, ensure V1 appears if you plan on using Verbose (word) results. Otherwise, ensure that V0 appears if you plan on using Numeric result codes. Also make sure that if your modem has any dip swithces, that you set them to correlate with V1 (word) or V0 (numeric) depending on choice. -> NOTE 2: For the fastest possible setup with minimal time spent in your modem's user manual (especially if all this is new to you) follow these steps: a) Use Verbose result codes (V1 in any of your STARTUP strings). b) Supply Y to the YMODEMG parm described earlier. c) Delete all keywords starting with RC_nnnnn, ERC_nnnnn, ERCA_nnnnn, and ERCB_nnnnn. The n's merely represent digits. These keywords are described later in this chapter, and appear later on in your STARTUP.x file. STARTUP2 - see STARTUP1 STARTUP3 - see STARTUP1 (this string usually ends with &W) REINIT - this is the command your modem needs to reinitialize itself after every caller. This is usually ATZ. THIS FIELD MAY OPTIONALLY BE BLANK! NOTE: ATZ is interpreted differently on some modems than others. To some modems, it means to reinitialize from MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-13 Configuring MAGNUM nonvolatile ram (NRAM or NVRAM), to others it means to reset completely (factory settings). If you're not sure, leave this field blank! THIS FIELD MAY OPTIONALLY BE BLANK. NOTE: The MODEMRESET, STARTUP1, STARTUP2, STARTUP3 and REINIT fields should be blank if you're setting up this node as a "pipe node" or if setting it up via "null-modem cable" (in other words, if you're setting up this node as a non-modem node). ---<>--- IMPORTANT: --------- Your modem init strings within your STARTUP.x file(s) (ie: MODEMRESET, STARTUP1, STARTUP2, STARTUP3, REINIT, ANSWERCMD, ONHOOK, OFFHOOK), now allow you to imbed a Magnum escape sequence in order to send characters to your modem which you were unable to do before. The backslash character ( \ ) starts this escape sequence. For example, if you wish to imbed a semicolon within your ANSWERCMD string, your STARTUP.x file might look like this: ANSWERCMD: AT A\59F Note that the \ character is followed by 2 digits (59) which happens to be the ASCII decimal equivalent for the ; character, so what your modem would really be sent is: AT A;F The ; character was not possible to include in a string prior to this version because it denoted the start of a comment within your STARTUP.x files. Another use might be to imbed a CR (carriage return) character (ie: \13), or a double-quote ( " ) character (which is \34). Note that the rules for using the \ character to denote an escape sequence are as follows: Use the \ character as the beginning of an escape sequence. If \\ appears, then a single \ character is sent. If \ is followed by one or more digits (up to 3 digits maximum), then the ASCII character represented by the decimal value of the digits will be sent (ie: \13 will send a CR character. If the \ is followed by a non-digit, that character will be sent. If you wish to send a " followed by the character 5, then the following must be used: \0345 because if you used: \345 you'd send the ASCII character 345 (which doesn't exist - the range is 0-255). \0345 sends the " character followed by the character 5 because the \ character uses up to (a maximum of) 3 digits that follow it. If you put a node in TEST mode (ie: "1 TEST" at the "Command => " prompt), you can experiment with using the \ character. Anything you type in TEST mode will be sent to your modem, and you will be able to see how your \ escape sequences are translated (you may have to issue AT E1 to enable echo mode). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-14 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM The \ character immediately followed by a tilde char (~) tells Magnum to pause for 500 miliseconds (example: \~\~ is a 1-second pause which is 2 500 milisecond pauses). ** IMPORTANT NOTE: If upgrading from a release prior to this feature, if ANY of your modem strings within any of your STARTUP.x file(s) contains the \ character, you'll need to double it (ie: \\) in order to send the \ character to your modem. ---<>--- DELAY1 - this is the delay (in miliseconds) of how long MAGNUM should wait after sending your STARTUP1 string before it should send the STARTUP2 string to your modem. This will vary with your CPU speed, modem, the speed with which your computer converses with your modem, and how fast your modem can process the string. DELAY2 - (see DELAY1) Specifies (in miliseconds) how long MAGNUM should wait after sending your STARTUP2 string before it should send the STARTUP3 string to your modem. DELAY3 - (see DELAY1) Specifies (in miliseconds) how long MAGNUM should wait after sending your STARTUP3 string before continuing. NOTE: If any of your STARTUPn fields are blank, use a minimal time delay for the corresponding DELAYn field (ie: 50). DTELOCKED - as mentioned earlier, some modems can communicate with the DTE (computer) at a much higher baudrate than they can over the phone lines. For these modems, especially those with MNP (Microcom Network Protocol), you can increase efficiency (throughput) by locking the DTE. Answer Y to lock the DTE, or N not to. If N, the DTE speed will match that of the incoming callers baudrate. -> NOTE: If you're using a modem such as the US Robotics Dual Standard, the Intel V.32, Hayes Ultra, or just about any modem capable of v.32 (9600 baud) communications, supply 19200 for the BAUDRATE parm above, and Y to the DTELOCKED parm. If you'r using a coprocessor card such as Artic or Digiboard, supply 38400 baud to the BAUDRATE parm. See the BAUDRATE parm described earlier in this chapter. ANSWERTYPE - Accepts a value of A, R or D. MAGNUM can be configured to answer the phone, or it can let your modem answer the phone. If you select A for auto-answer, your modem will answer the phone and MAGNUM will respond once a connection is established because the modem will send MAGNUM a result code. If you select R for ring-detect, MAGNUM will issue the command to the modem to answer the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-15 Configuring MAGNUM phone. Note that modems using the AT command set should have S0=0 as part of their init strings if using answertype of R; or S0=1 if answertype of A. NOTE: If using the callback module, all incoming modem nodes should be set to answer the phone via parm R (ring detect)! NOTE: Normally, you will not use D as an answertype. D is for Data-Carrier-Detect and is for use in specailized situations. This is is for certain WANs in which a "modem" appears to be present, but only the presence of a carrier is used to determine an incoming call. The baudrate of the incoming call will always be equal to the BAUDRATE parm. OPENMODE - Accepts a value of S or N. MAGNUM can open the communications ports as shared or nonshared. MAGNUM will work fine either way, however we strongly recommend that in a multitasking operating system such as OS/2, you choose N (nonshared). Choosing N guarantees that no other program will open the comport and ruin a session in progress. Choosing S will cause MAGNUM to open the port as shared, meaning any other program can also open that same comport. ANSWERCMD - Modem answer command string. For AT command sets (Hayes & compatible), the command is ATA. ONHOOK - Modem command to go onhook (hang up). AT command sets: AT H0 OFFHOOK - Modem command to go offhook (pick up the phone but don't answer it) - AT command sets: AT H1 NOTE: If you wish to turn off the speaker at this point, supply AT H1M0 ESC_CMDMODE - the command string which places the modem in command mode. AT command sets: +++ ESC_GRDTIME - Guard time (in miliseconds) for the modem to recognize the string for ESC_CMDMODE and place the modem in command mode. GO_ONLINE - the command string which causes the modem to go back online from a ESC_CMDMODE escape. AT command sets: AT O END_OFFHOOK - acceptable parms are Y or N. If Y (yes), the modem will place the phone offhook when you decide to end the MAGNUM BBS program (the modem must remain on in order for this to work) by sending the commands you specified in the OFFHOOK parameter described earlier. If N (no), any remote callers will not get an answer - the phone will continue to ring until the remote caller's modem hangs up. --- IF you're using the "fast" setup (Verbose result codes, Y to the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-16 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM YMODEMG keyword, and supplied the VERBOSE_CONNECT parameter), OR if you have a modem capable of speeds greater than 19200 baud connect rates, then follow these steps: a) Supply N to the ERRORCHECK keyword (ie: ERRORCHECK: N) b) Delete (deletion is optional) all keywords starting with RC_ or ERC_ or ERCA_ or ERCB_, and disregard the description of those keywords below. RC_110 - result code returned by the modem for a 110 baud connection RC_150 - result code returned by the modem for a 150 baud connection RC_300 - result code returned by the modem for a 300 baud connection RC_600 - result code returned by the modem for a 600 baud connection RC_1200 - result code returned by the modem for a 1200 baud connection RC_2400 - result code returned by the modem for a 2400 baud connection RC_4800 - result code returned by the modem for a 4800 baud connection RC_9600 - result code returned by the modem for a 9600 baud connection RC_12000 - result code returned by the modem for a 12000 baud connection RC_14400 - result code returned by the modem for a 14400 baud connection RC_16800 - result code returned by the modem for a 16800 baud connection RC_19200 - result code returned by the modem for a 19200 baud connection ERRORCHECK - answer Y (yes) to indicate an error-correcting modem is being used (ie: a modem with MNP,ARQ and/or LAP protocol), otherwise answer N (no). ERC_110 - modem result code for error-correction connect at 110 baud ERC_150 - modem result code for error-correction connect at 150 baud ERC_300 - modem result code for error-correction connect at 300 baud ERC_600 - modem result code for error-correction connect at 600 baud ERC_1200 - modem result code for error-correction connect at 1200 baud ERC_2400 - modem result code for error-correction connect at 2400 baud ERC_4800 - modem result code for error-correction connect at 4800 baud ERC_9600 - modem result code for error-correction connect at 9600 baud ERC_12000 - modem result code for error-correction connect at 12000 baud ERC_14400 - modem result code for error-correction connect at 14400 baud ERC_16800 - modem result code for error-correction connect at 16800 baud ERC_19200 - modem result code for error-correction connect at 19200 baud ERCA_110 \ Some modems require additional error-correcting result . \ __ codes (ie: a different one for MNP, one for LAP, etc). . / If your modem requires additional codes, they go here. ERCA_19200 / Leave blank if not used by your modem. ERCB_110 \ Some modems require additional error-correcting result . \ __ codes (ie: a different one for MNP, one for LAP, etc). . / If your modem requires additional codes, they go here. ERCB_19200 / Leave blank if not used by your modem. - - - Directory Paths - - - MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-17 Configuring MAGNUM Now we can go into the BBS directory paths. Directory paths are FULL paths including the drive letter. For instance, E:\MAGNUM\PGM_DIR is a valid pathname, while MAGNUM\PGM_DIR is invalid (no drive and no root path). Not every path has to be unique, although we recommend it for maintenance sake, but technically you can use the same path in more than one place. Each pathname can be up to 65 characters in length (including the drive letter). You can optionally end your pathname with the \ character but it doesn't matter - if you don't, MAGNUM appends one internally anyway. PROGRAM_DIR - This defines the directory which holds the actual MAGNUM BBS program(s). We use E:\MAGNUM\PGM_DIR NOTE: The PROGRAM_DIR parm should be on the same logical drive as the WORK_DIR parm (below). SESSION_DIR - This defines the directory which holds session data. We use E:\MAGNUM\SES_DIR BULLETIN_DIR - This defines the directory which holds bulletins and newsletters. We use E:\MAGNUM\BUL_DIR MENU_DIR - This defines the directory whcih holds any menus you create. We use E:\MAGNUM\MNU_DIR HELP_DIR - This defines the directory which holds the help files. We use E:\MAGNUM\HLP_DIR DISPLAY_DIR - This defines the directory which holds the display files. We use E:\MAGNUM\DSP_DIR EXTERNAL_DIR - This defines the directory which holds external programs. We use: E:\MAGNUM\EXT_DIR RJE_DIR - This defines the directory which holds RJE specific stuff. We use: E:\MAGNUM\RJE_DIR MSG_DIR - This defines the directory which is the parent to the message subdirectories. We use: E:\MAGNUM\MSG_DIR WORK_DIR - This defines MAGNUM's work directory. We use: E:\MAGNUM\WORK_DIR\1 for node 1 (STARTUP.1), E:\MAGNUM\WORK_DIR\2 for node 2 (STARTUP.2), etc. NOTES: - Each node should have its own, unique WORK_DIR - The WORK_DIR should be on the same logical drive as the PROGRAM_DIR USERS_DIR - This defines the directory MAGNUM uses for logging answers for user-generated questionairres, user NotePads, and Extended Msg & File pointers. We use: E:\MAGNUM\USER_DIR SYSOUT_DIR - This defines the directory for system output (ie: Activity logs, chat logs, user responses to questionnaires, etc). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-18 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM Now comes the file directories. As with the other directories, you have up to 65 characters each, and must include a full path including drive. You can have up to 26 file directories labeled A to Z. You should try to give descriptive names to the directories. The keywords for these entries are FILEDIR_A thru FILEDIR_Z. See the example STARTUP.X file for the way we use them. After defining the file subdirectories above, you now need to define descriptions. You have up to 40 characters each to describe the contents of the directories. You can have up to 26 file directory descriptions. The keywords for these entries are FILEDES_A thru FILEDES_Z. See the example STARTUP.X file for the way we use them. You can have up to 26 message areas labeled A thru Z. Whatever subdirectory you supplied for the MSG_DIR parm, the installation program (MAGINST.EXE) will create 26 subdirectories under the MSG_DIR directory. (ie: E:\MAGNUM\MSG_DIR\A ... E:\MAGNUM\MSG_DIR\Z). More on the MAGINST.EXE program later - for now, the completion of editing the STARTUP.X files is crucial. Like the FILEDES_x parm, the MSGDES_x parm is similar. You give descriptive headings for each of the MSGDES_x parms (up to 40 chars each). See our STARTUP.x file(s) for examples of how we use them. Now comes the BBS Parameters: BBS_NAME - this is where you give your BBS a name (up to 40 characters). BBS_STARTED - this is where you tell MAGNUM what date you'd like MAGNUM to show users as the starting date of the BBS. TTL_CALLS - this is where you tell MAGNUM how many calls your BBS has taken at the time of this creation. Ordinarily this would be 0, but some sysops switching systems want to display how many calls THEY'VE had - not this particular software. SYSOP_FIRST - the sysop's first name SYSOP_MIDDLE - the sysop's middle name or initial (LEAVE BLANK IF NONE) SYSOP_LAST - the sysop's last name PAGING_BEGIN - the sysop's beginning paging time (in seconds from midnight). To calculate seconds from midnight (00:00), take the desired time in military format (ie: HH:MM or 14:30 for example) and use the formula (HH * 3600) + (MM * 60). PAGING_END - the sysop's ending paging time (in seconds from midnight). See the description of PAGING_BEGIN to derive seconds from midnight. OPEN_BOARD - Y=sysop is running an open board (anyone can call). N=sysop MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-19 Configuring MAGNUM is running a closed board - sysop must pre-enter the users who are allowed access to the board. Pre-entering users in a closed system is accomplished by setting up the local node as an open system, and logging on from the console as the new user. REUSE_DEL - If you delete users, this option will let you assign a new user to an old user's ID. Answer Y to re-use deleted ID's. Answer N not to re-use deleted ID's. Bear in mind that Magnum's user database is not packable, meaning that if you have deleted users they will remain as deleted users forever (or until you change this parameter to Y and recompile the STARTUP.x file with the MAKEMBBS.EXE program). If you'll be setting this field to Y (yes), users will only be re-used if: - They are deleted, and - the REUSE field of the deleted record is Y, and - the new (replacement) user has the same first letter of their last name as the deleted user. NEWUSER_LVL - this parm tells MAGNUM what security level to assign to a new user. This can range from 0 to 9999. CONFIRM_NEWRESP - Optional. Supply Y (yes) or N (no). The default is N. If you supply N (no), Magnum will not confirm new user user logon responses with "Is this correct (Y/N) => " prompts when new users respond to the prompts of address, city, state, zip, country, telephone numbers, etc. Instead, the new user will have a chance to update their responses at the end of all of the new user logon questions. We recommend the default of N. This keyword exists only for compatibility with previous Magnum versions which confirmed every response. The confirmation of every response however, is frustrating and extraneous. GET_PHONE - Y=ask new users for their telephone numbers. N=don't ask. GET_DOB - Y=ask new users for their date of birth. N=don't ask. GET_COMPUTER - Y=ask new users for the computer brand. N=don't ask. GET_QUESTION - Y=force new users to fill out the new user's questionairre. N=no questionairre. GET_COMPANY - Y=Prompt user for whether they have a company name and collect the name of their company if they do. N=Do not prompt for company and do not collect company name information. GET_ADDRESS - Y=Collect mailing address information from the user. N=Do not collect mailing address information. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-20 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM GET_DATEFMT - Y=Ask new user for date preference (US or European). N=Use System Date Format for new user (obtained from the DATEFORMAT keyword described earlier). The user can change this later on through the [E]nvironment section of the main menu. GET_INTERESTS - Y=Ask new user for their areas of interest (for cross-reference capability). N=Do not ask new user for areas of interest. The user can change this later on through the [E]nvironment section of the main menu. MILC_CHAR - Optional. The parm you supply for this keyword will override the default MILC command character of '@'. MILC is the embedded command language Magnum uses in your display files. These embedded commands begin with a special character known as the MILC_CHAR. NOTE: characters with decimal values of 0 to 32 (hex 0 to hex 20) will not be accepted. Alphanumeric characters (A-Z, a-z, 0-9) and punctuation characters will NOT be accepted: !,.?"':;() CAUTION: If using someone else's MILC command file (from another BBS), chances are very high that they're using the @ character; you must be sure to change this to the MILC command character you define for your system. If you'll be overriding the MILC command character, use extreme caution in selecting a new character! Avoid the use of characters which may appear within a normal message (ie: %$#*[]{}\/<>+-&). Try to pick a not-so-common character such as the ~ or ^ character. MSGMILC_CHAR - Optional (default = ^). The parm you supply for this keyword will override the default MSGMILC command character of '^'. The character that denotes the start of a MILC command within message text should be something other than the '@' character because message text may contain reference to an Internet E-mail address such as someone@someplace.com (if @ were the MILC command character, Magnum would attempt to process (or remove) the @s of @someplace in this example). INTERNET_DOMAIN_NAME - Optional. The parameter for this keyword is the internet domain name of your system as its known on the Internet. You need to arrange for a domain name (UUCP DNS service) with your internet provider in order to provide the parm to this keyword. The default parm is a null entry (no domain name). NOTE: Internet E-mail requires the optional MAGUUCP module. INTERNET_TIMEZONE - Optional. The parameter to this keyword is the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-21 Configuring MAGNUM [internet] time zone your system is located in. This parameter is only necessary if you intend to use Internet e-mail. The parameter is the standard time zone notations such as PST (Pacific Standard Time), EDT (Eastern Daylight Time), GMT (Grenwich Mean Time), etc. The western-most portion of the U.S. mainland (ie: California, Oregon, Washington) is on PST or PDT depending on whether daylight savings time is in effect. The eastern-most portion of the U.S. mainland (ie: New York, Massachusetts, Maine, D.C., Florida, etc) is on EST or EDT depending on whether daylight savings time is in effect. There's two other time zones between eastern and western coasts such as Mountain time (MDT, MST), and Central time (CDT, CST). There are other time zones depending on where the BBS's physical location is (ie: lattitude, longtitude). NOTE: Internet E-mail requires the optional MAGUUCP module. LOGIN_OVERRIDE - Optional. If you supply a parameter to this keyword, Magnum will override the built-in "LOGIN: First Name or /id# => " prompt with the string that you supply to this keyword. Note that you have 43 characters maximum, if the maximum is exceeded, it will be truncated to 43 characters without warning. The MAKEMBBS.EXE program will automatically append the " => " string to the end of your string, therefore the " => " string is not included within the 43 characters that you are allowed. MORE_ADJUST - Optional. The "- More -" prompt appears after each screenful of text if the user wishes it. A screenful of text is defined by the user. For example, if the user specifies 25 lines/screen, then Magnum will display 25 lines of text and the -More- prompt will appear on line 26 thus scrolling one line of previous text off of the screen on a 25-line CRT. The value you supply here will adjust for this. For example, if you supply -1, then the user's lines/screen will effectively become (25-1) or 24. This keyword is optional, and carries a default of 0 if not specified. Recommended values are -3 to 2. DATEPROMPT_MIXED - Optional. Takes a parameter of Y or N. Supply Y to have Magnum supply date prompts in mixed case (ie: mM/dD/yyyy or dD.mM.yyyy), or N to supply date prompts in uppercase (ie: MM/DD/YY or DD.MM.YYYY). This keyword is optional, the default is N. SHOW_CALLERNUM - Optional. If you supply Y to this keyword, Magnum will function as usual. If you supply N to this keyword, Magnum will suppress the "You are the nth caller on MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-22 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM node x" message when someone logs on. SHOW_DLS - If you supply Y to this keyword, Magnum will function as usual. If you supply N to this keyword, Magnum will suppress the information on the number of Downloads on each file during any file listings. REMOTE_MAIL - Optional. If you don't plan on using remote mail, you should either supply N to this keyword, or leave the keyword out alltogether (default is N). This field applies only to NEW (first time) users. This is where NEW users get their RMAIL field in their record from (see the RMAIL field in the chapter on MBBSEXEC); in other words, if you want new users to be able to use the remote mail facilities immediately, supply Y to this keyword. NOTE: Existing users on the system will be unaffected by this field. Write a .MEX file for bulk update of existing users (see MBBSEXEC). MENU_CLS - This keyword accepts a parm of Y (for YES), or N (for NO). The default parm is N (no). If Y, then Magnum will issue a clear screen command prior to displaying a menu. FREENODES - This keyword will normally have a blank parameter. However, you may supply the list of nodes which will disallow a call on the current node if any of the nodes in the list are free (available) for calls (ie: no one online on any of the nodes in the node list). Node numbers are to be separated by commas. Maximum of 60 characters. Node numbers can be in any order, and may contain any valid node numbers. Note that a node in the list is considered 'available' if it is active and waiting for calls. The node is considered unavailable if someone is online or if the node is inactive. Example: FREENODES: 1,2 LOGON_VERIFY - The parm can be either Y (yes) or N (no). The default is Y. If N, the system will go directly to the password prompt after entering a name or user id; no confirmation as to the person's identity will be prompted for. DUPLICATE_LOGONS - Prior to version 8.xx, Magnum has always allowed duplicate logons (ie: the same user can be logged on to more than one node at the same time). This is now a configurable parameter. Valid parms are Y (allow) or N (disallow). The default is N (disallow). POLL_LOOP_WAIT - Version 7.00c of Magnum had a hard-coded poll-loop delay of 30 miliseconds which answered the modem line fast, started sessions fast, and recognized and reset terminated sessions fast. Version 8.xx changed this hard-coding to 60 miliseconds which is a little slower but uses less cpu time. This keyword allows you to set your own value. The default is 60 miliseconds, and the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-23 Configuring MAGNUM acceptable range is 0 to 1000. Now that this is a configurable parameter, you can fine-tune your system to your liking. --> NOTE: This keyword/parm is ignored for all STARTUP.n files except for the STARTUP.n file for your CONSOLE NODE! OUTSIDE_MAIL_ID - The ID number of the account for "outside mail". This is the account ID where any incoming 'outside mail' goes to when a particular ID is not specified. Example: OUTSIDE_MAIL_ID: /500 NOTE: The above ID is used for example purposes only! You should supply /0 (feature disabled) if you're installing Magnum for the first time. ALLOW_OUTSIDE_MAIL - The "new user default" as to whether to allow read/write access to/from the OUTSIDE_MAIL_ID account. If N, read/write access to/from mail accounts other than U or M is denied. The default is N. SHOW_EXTDESC - New User default for whether to show extended (long) file descriptions during file listings. The parameter can be Y (for YES) or N (for NO). If this keyword/parameter is omitted from the STARTUP.n file(s), the default is N. Note that users can choose to turn this on or off for themselves via the [E]nvironment option of the main menu (if allowed). ALLOW_HANDLES - Default for whether handles (alias names) can be used. If Y, then a new user (one who's logging on for the first time) will be prompted as to whether they wish to use a handle (AFTER they've entered their normal name). If this keyword/parameter is omitted from the STARTUP.n file(s), the default is N. FILEGROUP - Optional. Default FileGroup (0-255) for new user. Leave out or set to 0 if not using the Extended FileBase Module. MSGGROUP - Optional. Default MsgGroup(0-255) for new user. Leave out or set to 0 if not using the Extended MsgBase Module. NOTE: The FILEGROUP keyword should only be used by those sysops with the optional Extended FileBase Module. The MSGGROUP keyword should only be used by those sysops with the optional Extended MsgBase Module. Even with these modules, the use of these keywords are optional, and if not supplied, will default to 0 (no FileGroup and/or no MsgGroup). The use of FileGroups and MsgGroups will significantly speed up the following functions (requires Extended MsgBase and/or Extended FileBase): MSGMENU_BASE, MSGMENU_BASEUP, MSGMENU_BASEDN, FILEMENU_BASE, FILEMENU_BASEUP, FILEMENU_BASEDN. These keywords are defined later in this chapter. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-24 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM NEWUSER_TIME - new user's daily time limit (in minutes) LINES_SCREEN - new user's default for number of lines per screen LOWEST_BAUD - lowest baud rate allowed FILE_U_AREAS - file upload areas assigned to new user (use letters A-Z) FILE_D_AREAS - file download areas assigned to new user (letters A-Z) FILE_L_AREAS - file list areas assigned to new user (use letters A-Z) MSG_R_AREAS - message read areas assigned to new user (use letters A-Z) MSG_W_AREAS - message write areas assigned to new user (use letters A-Z) MSG_L_AREAS - message list areas assigned to new user (user letters A-Z) MILC_CMDS - Default MILC commands in which a user is allowed to imbed in messages s/he enters. (Formerly DISP_CMDS prior to v8.xx). RJE_AREA - area of file section designated for RJE results (ie: for use with the [F]ile menu's [M]ake command and for placement of resultant files from running RJE jobs). COMMENT_AREA - area of message section for "comments to/from sysop" STARTUP_TYPE - Session Startup (F=Fullscreen, W=Windowed) for this node FILEDES_AREA - area of message section for extended file descriptions PRIVMSG_AREA - area of message section for private system messages (messages generated by Magnum to a user). PRIVATE_MSGS - Y=private messages are allowed, N=private messages NOT allowed. NOTE: Comment to Sysop from main menu is *always* a private msg regardless of this setting. VERIFY_PHONE - Range is 0 to 255. If 0, phone number is not verified. If non-zero, the system will ask the user for phone number verification after every Xth call. (ie: if X is 5, the system will verify phone numbers for every 5th call the user makes to the system). This is an additional security check. NOTE: If the GET_PHONE parameter is N, then the VERIFY_PHONE parameter MUST be set to 0. VERIFY_DOB - Similar to VERIFY_PHONE except it verifies date of birth after every Xth call the remote user makes. If 0, no verification is asked for. NOTE: If the GET_DOB parameter is N, then the VERIFY_DOB parameter MUST be set to 0. DEL_MSGS - Y=user is allowed to delete messages, N=user cannot delete messages. NOTE: Y only allows user to delete messages addressed to/from his/her own user id. LOG_MSGS - Y=report each message read to the activity log - this can MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-25 Configuring MAGNUM make your activity logs very large very fast - especially with a large message base. N=do NOT record each message read to activity log (preferred). LOG_TIME - Y=prefix the time (hh:mm:ss) to each entry made in the activity logs in addition to start time of user session. N=do not prefix time to entries made in activity logs (start time of each user session is automatically entered in activity logs). SYSOP_LVL - the security level assigned to the Sysop. can range from 1 to 9999. This should be the highest security level of all of the users of the board. In our case, we're using a level of 1000. SYSOP_MAIL_LVL - Security Level needed to read private sysop mail. This would be for assistant sysops who you might want to be able to read private mail addressed to "sysop", but without necessarily having any other sysop priveleges. Level 900 is what we're using. DISPLAY_PW_FILES - Y=password protected files show up in the file listings. N=password protected files do NOT show up in file listings. UPLOAD_COMP - range is from 0 to 255. If X is 0, no upload compensation is granted, otherwise, upload compensation is X times the number of minutes spent uploading a file. For example, if X is 3, then if a user spends 5 minutes uploading a file, then 5 times 3 = 15. Therefore, the user would receive 15 minutes of upload credit in the form of 15 minutes of additional time left on the system. MSG_COMP - similar to UPLOAD_COMP, X can range from 0 to 255. X is in units of seconds per word. In other words, if X were 3 and the user entered a 100-word message, then 100 times 3 = 300. Therefore, the user would receive message compensation of 300 seconds (5 minutes). Actual compensation is rounded to the nearest minute. 1 minute and 30 seconds rounds to 2 minutes, whereas 1 minute and 29 seconds rounds to 1 minute. We have our system set to 1. UL_DL_RATIO - a ratio counter for number of files downloaded. If X is set to 10, then for every 10 files a user downloads, the system expects 1 file in return. The system will not allow further downloads until the ratio is met. If X is set to 0, no ratio is required - the user can download to their heart's content. DL_BYTES - maximum bytes a user can download per day (see TIME_UNIT). DL_FILES - maximum files a user can download per day (see TIME_UNIT). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-26 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM MAX_TIME_CALL - maximum time limit for any caller (in minutes). This field specifies how long any individual call can last regardless of security level or time allowed for the period. For example, if X is 60, then no caller will be allowed to exceed 60 minutes for any given call even though they might be allowed more than 60 minutes per day. The caller must either log off at the end of 60 minutes or be forced off by the system. The caller can call right back and be allowed another 60 minutes. This is to ensure that no caller ties up the system without giving someone else a chance. DAILY_TIME - new user daily time limit (in minutes). TIME_UNIT - Can be one of D (daily), W (weekly), M (monthly) or Y (yearly). If D, everything is as expected. If W, all parameters are internally multiplied by 7. If M, all parameters are internally multiplied by the number of days in the current month. If Y, all parameters are internally multiplied by the number of days in the current year (365 or 366). Taking a weekly (W) user as an example, a newuser default of 30 minutes per day would translate to 210 minutes per week (30 times 7). The user could use all of this time up in one day and not be allowed back on the system until next week. The number of daily downloads allowed, etc are all multiplied by 7. Although the period types of D, M, and Y have straightforward boundaries, W boundaries differ - for example, in 1989, January 1st fell on a Sunday, therefore, all W (weekly) boundaries will fall on a sunday for the remainder of 1989. For any given year, the boundary day which determines the change of week is the day that January 1st was for that year. This TIME_UNIT field is often referred to in the documentation as "period" or "period type". PRORATE - This parameter can be Y or N (yes or no). If Y, proration of any period type (TIME_UNIT) other than D (daily) will take place. This is best explained via example. If a user's period type is M (monthly), and the current month is June (30 days), then the user should have 30 times the daily parameters allocated. However, if PRORATE=Y, then if the user first calls the BBS on June 20, then MAGNUM will prorate the time left for actual days left in the month. In other words, June 20th means that only 10 days are left of the month, therefore, the user will only receive 10 times the daily allocation instead of the full 30. This proration will take place every logon. This may help lighten the extra load at the end of a period (week, month, year) when users scurry to get their time's worth in the last possible chance before a new period begins. PRINTER - A log is automatically kept by MAGNUM under the filename of ACTIVITY.X where X is the node number. This report can be MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-27 Configuring MAGNUM routed to a printer or other device (or other file but that would duplicate the ACTIVITY.X file). If you are running more than one node, do NOT choose PRN as the device for each node unless you are using the print spooler. Supply "nul" (without the quotes) if you don't want anything printed (ie: if the ACTIVITY.X report is good enough for you). SUB_FILEDEL - This parameter can be Y or N (yes or no). If Y, Magnum will subtract 1 upload credit each time a user deletes a file they uploaded to the system. If N, Magnum will NOT subtract any upload credits from the user's upload counter. FREE_DL_AREAS - This parameter specifies file areas that a user can download from without affecting their upload/download ratio counter. If you're using an upload/download ratio (ie: wanting 1 upload for every X files downloaded), you can define which areas files can be designated as "free" downloads. For example, if your company runs a support BBS with updates of your software available for download (regardless of how many downloads the user performed to date), you would designate those area(s) here. If you specify "ACH" (without the quotes), then all files downloaded from file areas A, C and H will be considered "free". (Free, in the sense that the user's upload/download counter is not incremented). BLOCK_WRITES - This parameter can be Y or N (yes or no). If Y, Magnum will send text to the comport in blocks (rather than single bytes at a time) whenever possible. This will improve the performance and efficiency of Magnum. On the down side, "remote snoop" (where you can call your BBS remotely and snoop on any node currently online with a caller) may result in lost characters on your remote "snoop" screen. NEW_MAIL - This parameter fan be one of three: "A" (without quotes) will ASK the user (at each logon) if they wish for Magnum to scan the message base for any "unread mail". "F" (without quotes) will FORCE a mail check (no prompts, just the mail check). "B" (without quotes) will bypass any mail checking or mail checking prompts. VERIFY_GOODBYE - This parameter can be Y or N (yes or no). If Y, the system will ask the remote user if they're sure they wish to log off (if the user is sure, they'll be prompted as to whether they wish to leave a comment to the sysop prior to disconnecting). If N, the system will not ask the user if they're sure about disconnecting, and will not prompt for a logoff comment, it will just log the user off (the ending quote will still be sent if the quote file is present, and the GOODBYE.BBS file will also be sent if present). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-28 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM BADCMDMSG - Y=Issue Message for unauthorized menu commands, N=don't NOANSI - Y=Deactive ANSI color, N=ANSI color ok If NOANSI is set to Y, color escape sequences are not sent by Magnum regardless of the user's color settings. The user will be unable to change their color settings from the [E]nvironment option. The new ANSI message editor will still function by using all ANSI escape sequences except color. NOXFRTIME - Y=Timer inactive for file xfers, N=Normal BBS xfr operation If NOXFRTIME is set to Y, the timer is disabled during file transfers. For example, if a user has a 30-minute time limit per day, the timer will stop during file transfer, enabling the user to download for hours on end. After transfer(s) are completed, the timer starts again from where it left off before the transfer. This situation is ideal for those companies who provide updates/fixes to their software via Magnum and, since each download saves the company a few dollars in labeling, packaging, shipping, etc, enabling this option ensures that every caller will be able to download any/every file they need with a single call. NOTE: If you supply Y to the NOXFRTIME keyword, not only is the timer disabled, but the following checks are also deactivated: - UL/DL ratio - Maximum K-bytes downloaded per period - Maximum Files downloaded per period - Time remaining for the period MAINMENU_HDR - Optional. Overrides the header (title) the user sees upon entry into the main menu. The default main menu header is "Magnum OS/2 BBS - Main Menu". If this keyword is supplied, it will override the main menu header with what you supply here. Example: MAINMENU_HDR: ABC Corp - Main Menu You may specify up to 60 characters. FILEMENU_HDR - Optional. Similar to MAINMENU_HDR but for file menu. MSGMENU_HDR - Optional. Similar to MAINMENU_HDR but for message menu. RJEMENU_HDR - Optional. Similar to MAINMENU_HDR but for RJE menu. SYSMENU_HDR - Optional. Similar to MAINMENU_HDR but for Sysop menu. CPUTYPE_OVERRIDE - Optional. If you specified Y to the GET_COMPUTER keyword described earlier, Magnum will prompt the user as to what brand of computer their using. This keyword can override that prompt with your own. For example, to find out what modem brand the user MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-29 Configuring MAGNUM is using: CPUTYPE_OVERRIDE: What modem brand are you using You can supply up to 40 characters. Magnum will automatically append " => " (without quotes) when displayed to your users. The user can respond with up to 20 characters. The remainder of the configuration text file (STARTUP.x) allows you to define how you want menus to look. These are the internal menus which are dynamically built by MAGNUM. You'll see later how to create your own menu file, but internally, MAGNUM needs to know what security level gets to do what function, and what letter you wish to assign to the functions, and what descriptions you want for the functions. Menu definitions are as follows: KEYWORD: C,L,S where KEYWORD tells MAGNUM which function you are referring to, C tells magnum what letter of the alphabet you wish to use to call that function, L tells MAGNUM the minimum security Level needed to access that function, and S is a string up to 40 characters in length which gives a descriptive text of the function. See the sample STARTUP.X file for how we do it. For example, the "[Y]ell for Sysop" might better suit your taste as: MAINMENU_PAGESYS: P,5,[P]age the Sysop The above statement tells MAGNUM that P would call the function MAINMENU_PAGESYS if the user has a security level of 5 or greater. MAGNUM would show that part of the menu as: [P]age the Sysop However, if the user's security level is less than 5, then that part of the menu would not appear. In other words, only level 5 and above would see that menu selection. MAGNUM dynamically builds these menus according to the user's security level. Be careful not to duplicate call letters within a menu. In other words, it's ok to have a call letter of P appear in the main menu, the file menu, the message menu, etc - but P can only appear once within any individual menu (ie: You cannot have P for "[P]age Sysop" and for "[P]arms" in the same menu). The Descriptive text for commands (up to 40 characters) is completely up to the sysop configuring the system. the brackets surrounding the first letter of the description has no bearing whatsoever - it merely helps the user to know what command is what. "[M]essage Section" could just as easily be "M - Messages" or "M = MAIL" or "EMAIL ...........M" - whatever your preference. Be warned that MAGNUM generates a 2-column menu display such that column one is from phsyical columns 1 thru 40, while column two is from physical columns 41 thru 80. Although MAGNUM accepts descriptive text of up to 40 characters, you should maximize your text to 39 characters or less otherwise this is what can happen MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-30 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM with text using all 40 characters: If in the first column, the last character (column 40) will appear immediately before the first character of the second column (column 41); Likewise, if the second column (41 thru 80) uses all 40 characters, then when the character on column 80 displays, certain displays will cause an automatic CR/LF, leaving a blank line between this menu choice and the next one. Before getting into the actual menu configuration keywords, let's first explain two optional keywords: MENU_HILITE: - Allows you to specify a character and color which tells Magnum to change the color of the character immediately following it. Example: MENU_HILITE: ~12 This tells Magnum that the ~ character means to change the very next character to color 12 (see the MILC @A command for color number meanings). With this method, your menu choice definitions in your STARTUP.x file(s) can look like: MAINMENU_MSG: M,5,[~M]essage Section which tells Magnum that the character M is to be changed to color 12 (bright red). If the online user does not have their color settings on, the ~ character (or whatever character you specified in the MENU_HILITE parm) will simply be stripped, and no color change will happen. Note that this character will also be stripped for color users. NOTE: *** Do NOT use the [ character as the parm for the MENU_HILITE keyword!! MENU_COLOR: - Allows you to override the default color of 2 (green) in which dynamic menus are built. For example, to present your menus in brown: MENU_COLOR: 6 QWK_BBSID - Optional. The Parameter for this keyword is 1 to 8 characters for QWK mail. If not supplied, Magnum will use the last 8 characters of your serial# for the BBS ID. You can override this by providing your own 1 to 8 character BBS ID. Examples: QWK_BBSID: GILMORE or: QWK_BBSID: MAGNUM If you do not provide this keyword (and your parm), Magnum will use the last 8 digits of your serial# instead. NOTE: External Menus ALWAYS override the dynamic menus!! There are 5 menu sections - each with their own unique keywords as follows: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-31 Configuring MAGNUM --- MAIN MENU DEFINITIONS --- MAINMENU_MSG: takes user from main menu to the message menu MAINMENU_FILE: takes user from main menu to the files menu MAINMENU_RJE: takes user from main menu to the RJE menu MAINMENU_BULLETIN: takes user from main menu to the main bulletin file MAINMENU_QUESTION: takes user from main menu to the main question file MAINMENU_COMMENT: allows user to enter a private comment to sysop MAINMENU_PAGESYS: system pages the sysop MAINMENU_WHO: shows who's on the other nodes MAINMENU_CHAT: enters group chat mode MAINMENU_INITIAL: shows initial welcome screen(s) again (HELLO?.BBS) MAINMENU_USERS: takes user to the "search user database" area MAINMENU_PARMS: allows user to change parameters in their profile MAINMENU_STATS: shows system statistics MAINMENU_CHILD: takes user to the main "child" file (door menu) MAINMENU_NEWS: takes user to the main "news" file MAINMENU_GOODBYE: logs user off and disconnects MAINMENU_EXPERT: toggles expert mode on/off MAINMENU_HELP: displays help file for main menu MAINMENU_SYSOP: takes user into the sysop menu section MAINMENU_OPT1: displays file MAINOPT1.BBS from DISPLAY DIRectory MAINMENU_OPT2: displays file MAINOPT2.BBS from DISPALY DIRectory Be careful in setting up the security levels - if the security level for MAINMENU_GOODBYE is higher than the lowest person's security level, then the user with the lower security level will not be able to log off! S/he will have to break the connection at their end! Likewise, if MAINMENU_HELP is too high, users with lower levels will not be able to get help! Also, make sure that the MAINMENU_SYSOP level only allows YOU (or someone you trust) to access the Sysop menu, otherwise someone could cause a lot of damage to your system! --- Message Menu Definitions --- MSGMENU_QUIT: Allows user to quit msg section. return to main menu MSGMENU_UPDT: Allows user to change message area(s) MSGMENU_READ: Allows user to enter the "read messages" submenu MSGMENU_SCAN: Allows user to scan messages MSGMENU_ENTER: Allows user to enter a message MSGMENU_KILL: Allows user to kill (delete) a message addressed to or from their own ID. MSGMENU_SRCH: Allows user to perform a text search. MSGMENU_CHECK: Allows user to check for their own personal mail. MSGMENU_GOODBYE: Logs user off and disconnects. MSGMENU_HELP: Displays the help file for the message section. MSGMENU_OPT1: Displays file MSGOPT1.BBS from DISPLAY DIRecory. MSGMENU_OPT2: Displays file MSGOPT2.BBS from DISPLAY DIRectory. MSGMENU_BASE: Change Msg Base. Requires 'Extended MsgBase module'. MSGMENU_BASEUP: Moves to next MsgBase (requires extnd MsgBase) MSGMENU_BASEDN: Moves to preceding MsgBase (requires extnd MsgBase) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-32 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM NOTE: If you're not using (or don't have) the optional extended MsgBase module, then the security levels of MSGMENU_BASE, MSGMENU_BASEUP and MSGMENU_BASEDN should be set to a level higher than that of the Sysop so that these menu choices will not appear online. --- File Menu Definitions --- FILEMENU_QUIT: Allows user to quit file section. Returns to main menu. FILEMENU_INFO: Displays detailed info on a file, including extended description if it exists. FILEMENU_LIST: Lists available files by section(s). FILEMENU_DL: Allows user to perform download(s). FILEMENU_UL: Allows user to perform an upload. FILEMENU_NEW: Allows user to perform a new files search by section and date FILEMENU_SRCH: Allows user to search file names and the brief description for a string of text. Can filter by date too. FILEMENU_STATS: Displays user's statistics for the period and in ttl FILEMENU_GOODBYE: Logs user off and disconnects. FILEMENU_HELP: Displays help file for the files section. FILENENU_EXT: Externally accesses ARC or ZIP file for list/view/dl FILEMENU_READ: Allows user to read any ASCII text file. FILEMENU_CHANGE: Allows user to change any file s/he uploaded. FILEMENU_MAKELIST: Allows user to make an ARC'd or ZIP'd file listing of available files by sections desired and dates. FILEMENU_OPT1: Displays file FILEOPT1.BBS from DISPLAY DIRectory. FILEMENU_OPT2: Displays file FILEOPT2.BBS from DISPLAY DIRectory. FILEMENU_BASE: Change FileBase. Requires 'Extended FileBase' module FILEMENU_UTILS: Utilities. Lets users Mark files, unmark, view, etc. FILEMENU_BASEUP: Moves to next FileBase (requires extnd FileBase) FILEMENU_BASEDN: Moves to preceding FileBase (requires extd FileBase) NOTE: If you're not using (or don't have) the optional extended FileBase module, then the security levels of FILEMENU_BASE, FILEMENU_BASEUP and FILEMENU_BASEDN should be set to a level higher than that of the Sysop so that these menu choices will not appear online. --- RJE Menu Definition --- RJEMENU_QUIT: Quits RJE section and returns to main menu RJEMENU_STATUS: For checking the status of any RJE jobs user started RJEMENU_LIST: List/Execute RJE menu (an external file you create) RJEMENU_DELETE: Kill an RJE job user started RJEMENU_FILES: Lists completed files (created by RJE job) ready for download RJEMENU_SYSOP: For Sysop use only RJEMENU_HELP: Displays help file for RJE section RJEMENU_GOODBYE: Logs user off and disconnects RJEMENU_OPT1: Displays file RJEOPT1.BBS from DISPLAY DIRectory. RJEMENU_OPT2: Displays file RJEOPT2.BBS from DISPLAY DIRectory. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-33 Configuring MAGNUM --- SYSOP Menu Definition --- SYSMENU_QUIT: Quits Sysop section - returns to main menu SYSMENU_CMD: Calls the OS/2 Command Interpreter (CMD.EXE) SYSMENU_PRINT: Prints the user database (to a file or device) SYSMENU_MSG: Msg Database Area -maintenance/adjustments of msgs SYSMENU_USER: User Database Area -maintenance/adjustments of users SYSMENU_FILE: File Database Area -maintenance/adjustments of files SYSMENU_ACTIVITY: For listing activity logs (listed backwards) or to remotely snoop on another session. SYSMENU_REMOTE: For remotely accessing the Sysop console. SYSMENU_STATS: Shows the status of the databases (user, msg, file, rje), and performs physical deletions of deleted or expired files and messages. Allows packing of message or file databases. SYSMENU_HELP: Displays the help file for the sysop section SYSMENU_GOODBYE: Logs user off and disconnects SYSMENU_OPT1: Displays file SYSOPT1.BBS from DISPLAY DIRectory. SYSMENU_OPT2: Displays file SYSOPT2.BBS from DISPLAY DIRectory. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-34 MAGNUM BBS (r) system for OS/2 Compiling your STARTUP.n file(s) Now that we've covered the text (source) file comprising the setup of a node, you are ready to "compile" this file with MAGNUM's MAKEMBBS.EXE program. MAKEMBBS scans your source file for errors and converts everything to a usable and readable "record" by MAGNUM BBS. The syntax for MAKEMBBS is: MAKEMBBS X Where X is the node number of your source file. If you entered "MAKEMBBS 1" (without quotes), MAKEMBBS would look for STARTUP.1 and "compile" it. If all goes well, there will be no error messages (warning messages are ok), your STARTUP.1 file will be deleted and a new file - MBBSINIT.1 will be created. DO NOT BE ALARMED that the STARTUP.1 file was deleted! There are good reasons for the deletion but rest assured, you could recreate the file with the following command: MAKEMBBS -1 >STARTUP.1 The minus sign (-) tells MAKEMBBS to recreate the STARTUP file from the MBBSINIT file. The reason for the deletion is so that you don't accidentally recompile the source file which will overwrite the actual record MAGNUM uses - the MBBSINIT file. If you overwrite the file, you will lose the updates MAGNUM makes to the record after every call - such as incrementing the number of calls received for that node, last caller's name, etc. For node 2, simply use the STARTUP.2 file instead, and change the 1's to 2's in the above examples. The same applies for nodes 3 and 4, etc. If you start MAKEMBBS without any parameters, it will "compile" ALL STARTUP.x files it finds into their respective MBBSINIT.* files! * * * NOTE: The Installation program created a file UNMAKE.CMD for you. By running UNMAKE, it will re-create all of your STARTUP.n files from the MBBSINIT.n files it finds. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-35 The MODEL statement If you're configuring STARTUP.2 (for example), and wish to model it after STARTUP.1, the MODEL statement parm (1 in the above example) specifies which COMPILED file (MBBSINIT.n) to model after. Note that although the MODEL statement is an easy way to configure a node after an existing node, the following parms should be unique to each node: WORK_DIR NODE DEVICENAME TTL_CALLS (should be kept separately for each node) Therefore, your STARTUP.2 file might look as follows: MODEL: 1 WORK_DIR: d:\magnum\work_dir\2 NODE: 2 DEVICENAME: com2 TTL_CALLS: 3437 Note that the MODEL statement must be the first statement in the file, for anything prior to this statement will be overwritten. Anything after this statement will be used as supplied. Also note that the NODE parm need not be specified, the makembbs.exe compiler will supply the proper node parm for you. ANY (and/or all) keywords/parameters are allowed after the MODEL statement. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-36 MAGNUM BBS (r) system for OS/2 SPECIAL.n files: Detecting Error-Correction, FAX callers, etc As mentioned earlier, the Verbose (V1) method of setup is not only the easiest (and preferred) method of setup, but also loses the capability of detecting error-correcting modems. This can be overcome with the use of the SPECIAL.n file(s). The use of these files is extremely powerful, and although not necessary for now, you can always come back to this section later to find out how to implement these files. With SPECIAL.n file(s) [which are to be located int the PGM_DIR], you have the ability to program your own actions based on modem result codes! We recommend the VERBOSE modem setting (AT V1) for this. The way it works is as follows. When your modem answers an incoming call, the two modems begin a "handshake" procedure. During this handshake, your modem may return many different information strings to Magnum, such as CONNECT, CARRIER, FAX, ARQ, MNP, LAP, etc. Beginning with this release, you can act on any one of these through an ASCII text file which you create by the name of SPECIAL.n (where n is the node#). These SPECIAL.n files are optional, and you can have one for each node, any node, or none. These SPECIAL.n files are to be located in your PROGRAM DIRectory. By way of example, suppose you have a fax-modem on node1 which returns the word FAX if it determined that the remote caller is a fax machine. Your SPECIAL.1 file might look like this: FAX { ex c:\fax\faxpgm.exe %com% } ARQ { ec } LAP { ec } MNP { ec } When you start your BBS (MBBS.EXE), it reads the SPECIAL.n (where 'n' matches the node number of the corresponding STARTUP.n file). When the modem returns word results (such as FAX), Magnum compares it against the keywords in your SPECIAL.n file for that node. Your keywords must end with the { character. When it finds a match, it performs the statements it finds for that keyword until the } character is reached. In the above example, when it matches on FAX, the one statement between the curly brackets tells Magnum to EXecute the program c:\fax\faxpgm.exe and pass it the handle of the comport. As you may have guessed, one of the allowable program statements is EX, which means EXecute. In passing command-line arguments to the program to be executed, you may specify any parameters you wish, however, the following parameters have special meaning: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-37 SPECIAL.n files: Detecting Error-Correction, FAX callers, etc %com% - Magnum will replace this with the comport handle. %baud% - Magnum will replace this with the baudrate (DCE). %device% - Magnum will replace this with the device name. There are other allowable program statements. In the above example, the keyword ARQ has as its statement EC - this program statement tells Magnum to treat the connection as an error-correcting connection. For those of you using Verbose modem codes, this would be the means of determining and setting the connection to error-correction = TRUE. Other error-correction word results are MNP and LAP. You are not limited to one program statement between the { and } braces. Other allowable program statements are: PAUSE nnnnn - Pauses nnnnn miliseconds (ie: 3000 = 3 seconds). SEND string - Sends "string" to the modem. "string" is meant to be a message to the user. Modem commands (ie: AT) will not work once carrier is raised. EX pgm [parms] - We covered this above. EC - No parms required (or allowed). Covered above. LOG - No parms required (or allowed). Writes to the ACTIVITY.x file the string that the modem returned upon carrier (ie: CONNECT 14400/ARQ/V42). Only one LOG statement can be used per file. Usual usage: CONNECT { log } or: ARQ { ec log } x cmd | * cmd - Any commands that you can type at the MBBS.EXE "Command => " prompt may also be supplied as a program statement here. NOTE:-At this time, only 5 modem codes (and thus 5 pairs of { and } program statements) are the maximum allowed. This should be more than adequate. Most of the modem codes you would probably deal with are: MNP, LAP, ARQ, FAX Once again, you are not limited to the above modem codes, you can use (and act on) any modem code that your modem returns. The above list of 4 modem codes are merely what we feel would probably be the most widely used. -The EX program statement does not actually start any programs, it merely sets the program to be started ONCE CARRIER IS RAISED! Once the program is actually started, it will start in its own session, and Magnum will terminate the program immediately in the event of a dropped carrier! If you're using the %device% keyword as part of the EX program statement, you should have the OPENMODE parm of your STARTUP.x file for that node as S (shared). -The modem codes (ie: FAX) returned by your modem almost never appear on a line by themselves. Keep in mind that the words MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 1-38 MAGNUM BBS (r) system for OS/2 SPECIAL.n files: Detecting Error-Correction, FAX callers, etc you're searching for in your SPECIAL.n file(s) (ie: FAX, ARQ, etc) are compared for in your actual modem result strings by checking to see if the word occurs at any point in the string. In other words, if you're searching for ARQ, your modem may actually return: CONNECT 9600/ARQ This will match the ARQ word in your STARTUP.n file because ARQ does indeed occur within the modem result string. -The SEND program statement will work once carrier is raised. Keep in mind that once the commands within your file have finished, the regular program, trademark and copyright notices will be sent to the remote modem (but a 'clear-screen' command is sent first). This is the purpose of the PAUSE command - you may want to use the PAUSE command after your last SEND statement to make certain the user has enough time to read your SEND statements. DO NOT USE the SEND statement until after carrier is raised (usually indicated by CONNECT). -If you make any changes to a SPECIAL.n file, in order for the changes to "take", you must deactivate the node (x INACTIVE), and re-activate it (x ACTIVE) [ x=node# ]. -Only .EXE programs are allowed. If you wish to run a .CMD file, your EX statement should look like this: EX C:\OS2\CMD.EXE /c SOMEFILE.CMD and you could also include any command-line parameters after the .CMD filename. Note the /c (lowercase) - this is mandatory! - Note that all searching/matching for your modem keywords terminate upon raised carrier! CONNECT is usually the last keyword your modem will return, however, once CONNECT is returned, as far as Magnum is concerned, carrier has been raised! So if your modem is a FAXmodem and returns a string with the word FAX in it AFTER the string which contains the word CONNECT, the match for FAX will never materialize since carrier has already been raised. NOTE TO USERS OF FAX-MODEMS: Only certain FAX-MODEMS will work with your SPECIAL.n file(s). Your modem will work IF: 1) it returns the word FAX or some other word to indicate that the modem at the other end is a 'fax-modem' or 'fax machine'. The older fax-modems and some of the newer fax-modems must be PLACED into fax mode by software... if yours is one such modem, it will not work with your SPECIAL.n file. Your fax software that you call from the 'ex' statement of the SPECIAL.n file should be able to take a parameter of the device name or comport handle in order for this scheme to work. Your comport should be opened in shared mode (OPENMODE: S). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Directory Structure of MAGNUM Page 2-1 Creating Subdirectories *--->>> This Chapter is to be used in conjunction with chapter 6 <<<---* IMPORTANT: EACH NODE MUST HAVE ITS OWN, UNIQUE WORK_DIR! The Installation program has created several directories (under the MAGNUM directory) and has placed 0 or more files in each of those directories. Outlined below is a list of the directories and files belonging within those directories. Note that some files will not exist until runtime; others may not exist until YOU create them (these will be optional files, so they won't be necessary for BBS operation). Any files which were NOT installed into your subdirectories by the installation program (MAGINST.EXE) are optional files which you must create if you wish to have its functionality implemented. IMPORTANT NOTE: PLEASE READ THIS ENTIRE CHAPTER - CERTAIN MAGNUM FEATURES ARE IMPLEMENTED BY THE PRESENCE OR ABSENCE OF CERTAIN FILES!! YOU MAY SKIM THIS CHAPTER AT FIRST, THEN COME BACK TO IT LATER. The remainder of this chapter lists the file directory structure, the files within those directories, and the order of the displayable files. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 2-2 Directory Structure of MAGNUM PROGRAM DIRECTORY (PGM_DIR) PROGRAM DIRECTORY (PGM_DIR) MBBS.EXE - Main (parent) program for MAGNUM BBS MSESSION.EXE - Child program runs user sessions MAKEMBBS.EXE - Configuration compiler/disassembler GETFILES.EXE - File xfer pgm called by MSESSION.EXE PUTFILES.EXE - File xfer pgm called by MSESSION.EXE MBBSEXEC.EXE - Magnum BBS executive maintanence pgm RJEMONIT.EXE - RJE monitor program (daemon process) EMAILIN.EXE - Used for Internet E-mail. KILLPROC.EXE - Used internally by Magnum. STOPMBBS.EXE - Stops ALL MBBS.EXE and LOCALBBS.EXE programs running on this computer and on your LAN (if LAN is used). STOPRJE.EXE - Stops ALL RJEMONIT.EXE programs running on this computer and on your LAN (if LAN is used). MAGFILE.EXE - Utility program bulk-adds files to your file database(s). MAGDRIVE.EXE - Utility program to create input file for MAGFILE.EXE (above) of an entire drive (ie: a CD-ROM drive). MAGFUTIL.EXE - Utility program to optionally maintain/optimize your file database(s). Performs virtually every imaginable test. MAGNUM.CMD - Command file to change to drive & directory of PGM_DIR and start the Magnum BBS system. MAGPATH.CMD - Command file temporarily adds Magnum's paths to the system path for the duration of the OS/2 command screen or OS/2 command window. It's recommended to add the paths of your PGM_DIR, EXT_DIR and RJE_DIR directly into the PATH statement of your CONFIG.SYS file rather than to use this command file. UNMAKE.CMD - Command file invokes MAKEMBBS.EXE to recreate ALL of your STARTUP.n files from MBBSINIT.n files. STARTUP.x - (x=node #) Human readable/modifiable configuration file. MBBSINIT.x - (x=node #) Compiled format of your STARTUP.x file(s). ANNOUNCE.x - (x=node #) When a node is in the 'announce only' mode, each time an announcement is sent, Magnum logs this to a file in your PROGRAM DIRectory called ANNOUNCE.LOG FREENODE.x - As an example, on a system with 3 modem nodes on a rotary (ie: dial node 1 and connect to the first available modem), you can prohibit your callers from calling node 2 directly if node 1 is free, and disallow your callers from calling node 3 directly if either node 1 or 2 is free, etc. Refer to the MAKEMBBS.EXE program for the FREENODES keyword/parm which can allow you to do this. If any of the nodes are available for calls (with no one online on any of those nodes), the system will promptly disconnect the call. However, we realize this may be rude, so the system will check for the presence of a file in the pgm_dir by the name of FREENODE.x (where x is the current node that is taking the call) and display the contents of that file to the caller prior to disconnecting. In that MBBS.EXE displays the file, MILC commands are NOT available. The file should be a straight ASCII text file, and should probably be limited to 23 lines of text (although not necessary). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Directory Structure of MAGNUM Page 2-3 PROGRAM DIRECTORY (PGM_DIR) MBBS.ACE - File containing ACE (Automatic Command Execution) statements (events). ACE.LOG - Contains ACE results - updated whenever an ACE command is executed, and when system is started. REMAPDIR.x - (x=node #). Used to remap directories for those running additional copies of Magnum on their LAN. NOTMAIL.x - For display when node x is in 'mail only' mode. Displayed when a non-mail account tries to log on. TMP.ACE - Any command that can be typed at MBBS.EXE's "Command => " prompt can be optionally entered via a program you may be developing. Simply create a file called TMP.ACE in the PROGRAM DIRectory and write your commands (one per line, each line terminated by a CR/LF - in other words, it's an ASCII text file). No queued commands are allowed (as opposed to the MBBS.ACE file). Commands are to be written exactly the way you'd type them at the "Command => " prompt. After all the commands in the file are executed, Magnum will delete the file. Any text lines not starting with either a digit (node#) or the * character will be discarded. Magnum will check for the presence of TMP.ACE only once per minute. NOTE: This file (if it exists) is deleted by Magnum when Magnum (MBBS.EXE) is first started! This file is meant to be created/used while Magnum is actively running! ATENDx.ACE - Where 'x' is node number. This file can contain any commands in it that you could ordinarily type at the MBBS "Command => " prompt. When an online session for node x finishes, if this file exists, the commands within will be executed. Queued commands are not allowed. Like entering a command at the "Command => " prompt, the BBS essentially freezes until that command is complete. Try to refrain from running any programs at this point. This is an ASCII text file; commands start with * or a digit. MBBS.ICO - Icon file for MBBS.EXE. MSESSION.ICO - This Icon file is automatically used under OS/2 1.x whenever someone logs on. However, if you want this icon to be used under OS/2 2.x, create the file MBBS.ACE (or add to it) with the following statements: *,1 ICON d:\magnum\pgm_dir\msession.ico *,2 ICON d:\magnum\pgm_dir\msession.ico etc (for each node) where 'd:' is the drive letter of where your Magnum system is installed. MMPATCH. - The [optional] presence of this file invoked a fix in pre 8.xx Magnum versions. If this file is still present on your system you should delete it. CLEARBUF.FLG - If this file exists, Magnum will perform a read of the modem buffer prior to closing until no more characters remain in the buffer, or until the loop has completed 10 iterations. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 2-4 Directory Structure of MAGNUM SESSION_DIRECTORY (SES_DIR) SESSION DIRECTORY (SES_DIR) SPLITKEY.EXE - Rebuilds *.KEY files from USER.DAT RMAILMAP.EXE - For those with the Extended MsgBase module. Maps incoming msgs to specific msgbases. AMMO.MAG - Optional - used for Remote Mail. NOCHANGE.LST - Optional - defines unchangeable parameters within the [E]nvironment selection of the main menu. BADNAME.LST - List of unallowable logon names BADUPLD.LST - List of unallowable upload filenames NOANSCHK.LST - List of file extensions NOT to perform an ANSI check on after upload. COMPRESS.LST - Define external file compression pgms. USER.KEY - The Keyfile used during logons. USER_*.KEY - Sub-Keyfile used during logons. USER.DAT - The user database FILE.DAT - The main file database (FileBase 0). MSG.DAT - The main message database (MsgBase 0). RJE.DAT - The RJE database UTILIZ.DAT - The utilization database (optional) MILC.SUB - (Optional). If present, defines characters which are to be replaced (substituted) with other characters. QSECy.BBS - y=user security level. If this file exists, it will be displayed ONCE to users whose security levels match y. SECy.BBS - y=user security level. Like QSECy.BBS above, but displays every time. IDz.BBS - z=specific user id. If this file exists, it will be displayed ONCE to the user whose ID matches z. *.USR - Where * is an ID number; these files are transient and are created by Magnum for each user who's currently logged on and deleted upon logoff or dropped carrier. WHOS.ON - If you wish to override the display of the "[W]hos On" command with that of your own, simply create the file WHOS.ON in your SESSION DIRectory. The contents of this file should contain the MILC commands you wish in order to convey the information you wish to display during the "[W]hos on" command. Note that this file will NOT be used for information regarding a NEW (first time) caller - the default display will be used for a first time caller instead. The way the WHOS.ON file works is that it's similar to a displayable MILC file, but it's processed as soon as the password is entered. It's not displayed, but rather interpreted (MILC characters are replaced) and written to the nnnnn.USR file for that ID on that node. Whenever someone does a "[W]ho's On" from the main menu, Magnum simply displays the contents of each of the *.USR files it finds. *.USX - Where * is a user's ID number. The presence of any of these files (contents are unimportant) indicates to exclude this user from appearing in the "[W]ho's On" command. For example, the Sysop (ID: /0) may wish to exclude themselves by creating a 0.USX file. You may wish to exclude others too (ie: celebrities, CEO's, etc). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Directory Structure of MAGNUM Page 2-5 SESSION_DIRECTORY (SES_DIR) NOSHOW.RMM - For those using Magnum's Remote Mail (AMMO), part of the AMMO process is to place MsgMarkers within the MsgBases. Some Sysops don't want to see these MsgMarkers. If you wish to exclude MsgMarkers from showing up when reading your mail, simply create this file (contents are unimportant). --> NOTE: Version 8.xx eliminated MsgMarkers! There's no more need for this file unless you still have left over MsgMarkers from a version prior to v8.xx. Uid.MG - Where 'id' is the user's ID number. For those using the Extended MsgBase module. Identical to the msg .GRP files in format, if this file exists for a certain user ID, that user will belong to his own 'group' regardless of what msggrp they were originally assigned to. This file overrides any group assigned to the user. Uid.FG - Where 'id' is the user's ID number. For those using the Extended FileBase module. Identical to the file .GRP files in format, if this file exists for a certain user ID, that user will belong to his own 'group' regardless of what filegrp they were originally assigned to. This file overrides any group assigned to the user. HELLO.Q - The 'Welcome' file to be included in the QWK packet. No MILC commands should be placed in this file! NEWS.Q - The 'News' file to be included in the QWK packet. No MILC commands should be placed in this file! GOODBYE.Q - The 'GoodBye' file to be included in the QWK packet. No MILC commands should be placed in this file! FILECONT.BBS - Due to the nature of high-speed modems, large modem buffers and other factors, <Ctrl-X> is NOT always trapped during NonStop File Listing. For this reason, when a user chooses N (NonStop) at the FileListing's "More" prompt, Magnum checks for the presence of FILECONT.BBS in your SESSION DIRectory. If this file exists, Magnum will display the file to the user. Within this file, you can warn the user that during a nonstop file listing, they may not be able to break out of it! You may also prompt the user as to whether they're sure if they want to continue with their choice of Nonstop. Upon return, Magnum checks MILC variable @Z0 for the presence of Y or N. If it contains Y, Nonstop filelisting will continue. If N or any other character they'll be reprompted with the "More" prompt. The prior contents (if any) of the @Z0 variable will be preserved prior to the "More" function ending. An example of the contents of this file: NonStop file listing may not be stoppable! Choose [M]ake to get a downloadable listing of files. Continue with NonStop Anyway? (Y/N) => @Z0('yn'); BRDCAST.ALL - Optional text file you or an application program can create and place in your SESSION DIRectory. When MBBS detects the presence of this file it copies it to BRDCAST.n (where n is the node number) of all nodes that meet the following criteria: identical session directory MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 2-6 Directory Structure of MAGNUM SESSION_DIRECTORY (SES_DIR) as the session directory the BRDCAST.ALL file is found in; the node is active and a caller is logged onto that node. After making copies of this file to all nodes matching the above criteria, the original file (BRDCAST.ALL) is deleted. See BRDCAST.n (below) for information as to how Magnum processes BRDCAST.n files. BRDCAST.n - While a caller is online, MSESSION.EXE checks for the presence of a file in the SESSION DIRectory defined for that node for a file by the name of BRDCAST.n (where n is the node number). If the file is found it immediately stops whatever the online user is doing (unless they're entering a message or xfering a file) and clears the user's screen, displays the string: " * * * B R O A D C A S T * * *", then displays the BRDCAST.N file, and then presents the "PRESS ENTER" prompt. After the file displays and the user presses ENTER, the screen is restored to where they were prior to the display of the file and the BRDCAST.n file is deleted. The format of the BRDCAST.n file is an ASCII text file (each line terminated by a CR/LF pair) and may contain MILC commands! Because of the capability of containing MILC commands, the capabilities you build into broadcast files are only limited by your imagination (ie: E2/E3 file xfer, a broadcast 'menu', starting an interactive program w/ E0 or a background program w/ E1, or an immediate on-the-fly questionairre. Example: Did you just feel that earthquake? (Y/N) => @z2('yn'); @z2("Felt EarthQuake: "); etc. Its advised that you (or your application program) create a BRDCAST.n file or a BRDCAST.ALL file using a different name and then either rename or copy it to BRDCAST.n or BRDCAST.ALL depending on which one you wish. QWK.MAP - Map file for incoming QWK .REP (or QWK) packets. Refer to the text within this file for its usage. CONF_NUM.TXT - Text file shows how QWK conference numbers are created from Magnum MsgBase:ConfNum format. ACCTTYPE.x - The account TYPE for any user record can now be any character or letter you wish. Up until this point, only two account types existed: U for USER accounts, and M for MagnumMAIL accounts. These two types are still in use and always will be. However, in preparation for outside mail exchange with other mail formats, you can now assign an account type of other than U or M. For example, to exchange mail with a QWK 'net', you might assign a certain account for that purpose and classify it's type as Q (for QWK), or I (for Internet). If an account other than U or M logs on, Magnum will look in your SESSION DIR for (and display) the file ACCTTYPE.x (where 'x' is the account type) if it exists. This file can contain MILC commands to start an RJE or child (door) process to perform whatever it is you wish. This file displays after logon and BEFORE entry into the main menu. To set up a QWK 'net' account, you must log on via the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Directory Structure of MAGNUM Page 2-7 SESSION_DIRECTORY (SES_DIR) console as a new user, providing a mnemonic name such as "QWK GLOBALNET" or "GLOBALNET QWK" for example. Choose a default xfer protocol such as Zmodem. After the new account has been established, log off and then log on as Sysop (/0). Go into the Sysop menu and pull up the user record for the new account and change the account TYPE to Q (to denote QWK, but the letter could be anything other than U or M) . You should also create or modify the display file NEWMSG.BBS (in your DISPLAY DIRectory) to inform your users of ID's to/from outside mail networks (ie: enter a msg to ID /nnn for GLOBALNET, /yyy for ALTERNET, etc). NOTE: Account types other than U (user) will not invoke the standard HELLO?.BBS files or other display files prior to entering the main menu after logon, nonstop display is automatic, and PRESS ENTER prompts are bypassed. INTERNID.DAT - This file contains user-defined Internet E-mail addresses for your system. For example, if ID /0 (sysop) chooses the name "sysop" for their address, the full internet e-mail address will be sysop@domain.name where domain.name is the domain_name parm provided to the INTERNET_DOMAIN_NAME keyword in your STARTUP.x file(s). The first time someone logs onto your system after installing this release, this file will be created and initialized with the same amount of records as in your USER.DAT file, this may take some time but it will only happen once. New user default e-mail names will be idx where x=ID#. Example: /0 = id0@mybbs.com /1 = id1@mybbs.com /2 = id2@mybbs.com etc. idx is user-changeable (Environment menu option 27) to be any unique name up to 25 chars (the "@mybbs.com" will be appended during bbs functions but is not part of the 25 char limit). The user-changeable portion appears to the left of the @mybbs.com portion. DUP.UL - uploading of duplicate files are allowed if this file is present (but not recommended). To allow duplicate files to be uploaded, create the file DUP.UL in your SESSION DIRectory (must be 1 or more bytes in length - ie: put "Hello World" in the file to make it more than 1 byte in size). If this file is present, the system will bypass the check for duplicate files and allow the upload. To download, use the #nnnn method instead of filename. If you allow duplicate filenames for upload, the system will only check to see if a duplicate exists in the file area being uploaded to; Magnum will only allow duplicates in different file areas. PREDOB.BBS - When the GET_DOB keyword is activated in your STARTUP file(s), some people logging onto your system for the first time are sensitive about being asked their date of birth. If you create an optional file PREDOB.BBS in your SESSION MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 2-8 Directory Structure of MAGNUM SESSION_DIRECTORY (SES_DIR) DIRectory, you can alleviate their sensitivity with any text you wish. An example of the contents of this optional file might be "In the event you forget your password, we will need to know your date of birth for verification". MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Directory Structure of MAGNUM Page 2-9 BULLETIN, MENU, HELP Directories (BUL_DIR, MNU_DIR, HLP_DIR) BULLETIN DIRECTORY (BUL_DIR) BULLETIN.BBS - The Bulletin File. NEWSLTR.BBS - The NewsLetter File. QUESTION.BBS - The Question File. QUESNEW.BBS - The New-User Questionairre. MENU DIRECTORY (MNU_DIR) MAINMENU.BBS if any of these files exist, Magnum displays the file FILEMENU.BBS for the menu instead of the dynamically-built internal MSGMENU.BBS menu. SYSMENU.BBS RJEMENU.BBS HELP DIRECTORY (HLP_DIR) MAINHELP.BBS These are the "help" files Magnum looks for when a FILEHELP.BBS user wants help in the section of the BBS they're in. MSGHELP.BBS SYSHELP.BBS RJEHELP.BBS MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 2-10 Directory Structure of MAGNUM DISPLAY DIRECTORY (DSP_DIR) DISPLAY DIRECTORY (DSP_DIR) HELLO1.BBS - Displayed after logon /-------------------------\ HELLO2.BBS - Displayed after logon | NOTE: You may also have | HELLO3.BBS - Displayed after logon | extensions of | NEWUSER.BBS - Displayed for new user only | .SCR | BIRTHDAY.BBS - Displayed on user's birthday | See the chapter | GOODBYE.BBS - Displayed at logoff | on "Customizing | PRELOG.BBS - Displayed before logon | Magnum & Display | LOWBAUD.BBS - Displayed if baud too low | Files". | CLOSED.BBS - Displayed if a closed BBS \-------------------------/ OPEN.BBS - Displayed if running an open BBS and new user not found in user database. QUOTES.BBS - Displays an ending quote (at logoff). PREUP.BBS - Displays prior to upload POSTUP.BBS - Displays after an upload PREDOWN.BBS - Displays prior to download POSTDOWN.BBS - Displays after download UDRATIO.BBS - (u/l to d/l ratio exceeded) PRELIST.BBS - (pre file-list message) NEWMSG.BBS - Displays when a user chooses "[E]nter New Message". This file is an ideal place to put some brief information as to what ID to write to for "Tech Support", "Marketing Information", etc. MAINOPT1.BBS - Displays from main [1] MAINOPT2.BBS - Displays from main [2] FILEOPT1.BBS - Displays from file [1] FILEOPT2.BBS - Displays from file [2] MSGOPT1.BBS - Displays from msg [1] MSGOPT2.BBS - Displays from msg [2] RJEOPT1.BBS - Displays from rje [1] RJEOPT2.BBS - Displays from rje [2] SYSOPT1.BBS - Displays from sys [1] SYSOPT2.BBS - Displays from sys [2] FILESRCH.BBS - Displays (if exists) in lieu of the built-in text when the "[T]ext Search" function of the file menu is chosen. FDIR_x.BBS - Displays when user chooses [L]ist command from Files menu, such that if user lists area G for example, FDIR_G.BBS will display prior to listing the files in area G. FDIR_x.* files are optional and will only display if the matching FDIR_x.* file exists. CAUTION: Avoid using MILC commands which halt the display or ask for user input because user's may wish to capture your entire entire listing while viewing it in a nonstop fashion. FDIRcnnn.BBS - For those with the Extended FileBase module. Identical in function to FDIR_x.BBS but for 'extended' FileBases (1 to 255). The naming convention is FDIRcnnn.BBS where c is the area within the FileBase, and nnn is the 3-digit (all 3 required) FileBase number. PREBADV.BBS - Displays if Mismatch in birthdate or phone# verification (see VERIFY_DOB and VERIFY_PHONE in chapter 1). See Ch 6. POSTBADV.BBS - Displays if Mismatch in birthdate or phone# verification (see VERIFY_DOB and VERIFY_PHONE in chapter 1). See Ch 6. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Directory Structure of MAGNUM Page 2-11 DISPLAY DIRECTORY (DSP_DIR) NEWMSG.BBS - If this optional file exists, it will be displayed when the user chooses "[E]nter Message" from the Message Menu. CMT2SYS.BBS - If this optional file exists, it will be displayed when the user chooses "[C]omment to Sysop" from the Main Menu. PREREAD.BBS - If this optional file exists, it will be displayed when the user chooses "[R]ead Messages" from the Message Menu. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 2-12 Directory Structure of MAGNUM EXTERNAL DIRECTORY (EXT_DIR) EXTERNAL DIRECTORY (EXT_DIR) ARC2.EXE - Used for creating, viewing, etc of compressed .ARC files. Not included in this distribution. You may download ARC201.EXE from our BBS (rename it ARC2.EXE) if you wish to have support for the .ARC compression format. PKZIP2.EXE \ Used for creating, viewing, etc of compressed .ZIP files. PKUNZIP2.EXE / ZIPCMT.x - Comments for uploaded .ZIP files. x=node#. When a user finishes uploading a new .ZIP file to the BBS, the contents of the file ZIPCMT.x will be added as a comment to the .ZIP file. CHKANSI.EXE - ANSI Escape Sequence Checker - called by both the message and file section - if this program detects a harmful ANSI escape sequence to redefine keyboard key(s), MAGNUM BBS immediately ends the user's session and locks them out of the system. You can delete or rename this program if you do not wish Magnum to use it (sometime false harmful escape sequences are inadvetantly reproduced by file compression methods such as ZIP, ARC, etc). UTILIZ.EXE - The Utilization reporting program. MAKEDOOR.BBS - Sample only. File shows how to construct a DOOR.SYS file specific to your BBS. Some modications are required. CHILDREN.BBS - Menu for external programs known as 'doors' on DOS BBS's. The way this works is that upon exit of displaying this file, the variable @Z0 should hold the program name (no path or drive, just program name - the program is expected to be found in the EXTERNAL DIRectory), variable @Z1 should hold command line arguments to be passed to the child (if any), and @N0 should have it's bits set as follows: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Directory Structure of MAGNUM Page 2-13 EXTERNAL DIRECTORY (EXT_DIR) 128 64 32 16 8 4 2 1 | | | | | | | | | | | | | | | \-> 1=echo user input to comport | | | | | | | 0=no echo (child handles echo) | | | | | | \----> 1=cooked mode | | | | | | 0=raw mode | | | | | \-------> 1=CR translates to CR/LF pair | | | | | 0=no translation to CR/LF pair | | | | \----------> 1=CR tranlates to LF | | | | 0=no translation to LF | | | \-------------> 1=CR translates to NUL | | | 0=no translation to NUL | | \-----------------> Not used | | \---------------------> 1=Mark the ACTIVITY.x handle as | inheritbale by the child | process. See MILC command @V92 | 0=ACTIVITY.x handle is not | inheritable by the child | process (default). \-------------------------> 1=Mark comport handle as inheritable by the child process. See MILC command @V0. 0=Comport handle is not inheritable by the child process (default). NOTE: For most doors, such as "adventure", the the following statement would be required: @N0=7; This would set bits 1, 2, and 4 on. To compute the value you need for any particular door, add up the bit "field" numbers which have their bits set to 1. For instance, in the above example, bit fields 1, 2 and 4 are each set to 1. Therefore, adding up bit fields (1+2+4) gives a result of 7. If bit fields 16 and 2 were the only ones set, then 16+2 = 18, thus your @N0 assignment would be @N0=18; MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 2-14 Directory Structure of MAGNUM RJE DIRECTORY (RJE_DIR) RJE DIRECTORY (RJE_DIR) When in the RJE section of the BBS, the [L]ist/Execute menu selection will look for, and display the file RJELIST.BBS (or RJELIST.SCR) in the RJE DIRectory. In our sample distribution, the following files have been placed in your RJE directory by the MAGINST.EXE program: RJELIST.BBS - Sample RJE list/execute menu. MSGLIST.EXE - Gathers mail, converts it to .QWK or Internet E-mail format. MSGLIST.RJE - RJE/MILC processing for offline mail. USERMSGS.CMD - Sample RJE command file for the MSGLIST samples above. ADDRJE.EXE - Adds RJE files to file database. For more info on this program, execute it without any parms. MARKUNRD.MEX - RJE process to unmark marked messages for a given user. MARKUNRD.RJE - Starts MARKUNRD.MEX GETQWK.RJE - RJE file handles uploads of .QWK files (offline mail). RJEQWK.EXE - Processes uploaded .QWK files (offline mail). **** All RJE programs are expected to be found in this subdirectory! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Directory Structure of MAGNUM Page 2-15 MSG,WORK,USER,SYSOUT Dirs (MSG_DIR,WORK_DIR,USER_DIR,SYSOUT) MESSAGE DIRECTORY (MSG_DIR) This is the MAIN MsgBase (MsgBase 0) where message files go. Any messages which are a description of an available file for download, will have the same filename as the downloadable file. MSG DIR is the parent subdirectory, and there MUST be 26 subdirectory entries within this directory, named A to Z. (IE: \magnum\msg_dir\a, \magnum\msg_dir\b ... \magnum\msg_dir\z). These 26 subdirectories will be created for you by the MAGINST.EXE program. WORK DIRECTORY (WORK_DIR) Temporary workspace used by Magnum during sessions. CAUTION: WE STRONGLY RECOMMEND A UNIQUE PATHNAME FOR EACH NODE USED IN YOUR BBS!! We recommend d:\MAGNUM\WORK_DIR\1 for node 1, d:\MAGNUM\WORK_DIR\2 for node 2, etc (where 'd:' is the drive letter your Magnum BBS system was installed on). CLEANUP.CMD --\ _CLEANUP.CMD >-> Technical: MSESSION.EXE creates a CLEANUP.CMD file GCLEANUP.CMD --/ in the WORK_DIR during an online session. When the session ends, MBBS.EXE will execute this command file in the background. When finished, the file is deleted. The CLEANUP.CMD file will also check for the existence of _CLEANUP.CMD in the WORK_DIR (note the _ character in _CLEANUP.CMD) and if it finds it, it will call that file and delete it when finished. The CLEANUP.CMD file will also check for the existence of GCLEANUP.CMD in the WORK_DIR (the G in GCLEANUP.CMD denotes a GENERAL cleanup command file) and if it finds it, it will call that file but will NOT delete it when finished. You (or your custom application program) can create a _CLEANUP.CMD and/or GCLEANUP.CMD file for selected or each WORK_DIR. Note that these cleanup command files are running in the background, detached, therefore no screen or keyboard I/O is allowed. Consider this capability identical to running an RJE (background) process that gets called whenever a session terminates. IMPORTANT: If you take advantage of the _CLEANUP.CMD or GCLEANUP.CMD files, execute your commands within those files as quickly as possible because a new CLEANUP.CMD file will be created immediately when the next caller logs on. SYSOUT DIRECTORY (SYSOUT) ACTIVITY.x - (x=cnode#) Activity Log for node x. SYSCHAT.LOG - The log of Chat between Sysop<->User. GRPCHAT.LOG - The log of Group Chat. *.R?? - ??=com port number (response files). Any file containing MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 2-16 Directory Structure of MAGNUM MSG,WORK,USER,SYSOUT Dirs (MSG_DIR,WORK_DIR,USER_DIR,SYSOUT) MILC commands to write answers to a response file will be, placed here. The name of the response file is the name of the file containing those MILC commands, but will have an extension of R?? (R for Response, ?? will be replaced by the node# 01, 02, etc). USER DIRECTORY (USER_DIR) If you allow your users access to MILC commands @Zx and/or @Nx, any messages they create containing the @Zx or @Nx commands which write output will be written to the same filename as the file containing these commands, but placed in this directory. Also, user NotePads will be kept in this directory. Additionally, the following file(s) may be present as your BBS gets used: DP*.ZIP - DataPointer file (* = user's ID) for Extended Msg & File bases. Holds info as to last new filesearch and msgread for each of the extended msg & file areas. U*.FMK - Where * is the user's ID number. Any such files contain a binary "list" of marked files the user may have marked or which Magnum may have marked for them. ID*.NPT - Where * is the user's ID number. This holds the NotePad Titles for this user. ID*.Nnn - Where * is the user's ID number, and nn is the NotePad number (00-99) for the user. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Directory Structure of MAGNUM Page 2-17 Order of Display Files Although a little premature for this, you will need to know the order of the display files for later: ANNOUNCE.x - displays only if node is used for "announce only" (x=node #) [logs each 'announcement' to ANNOUNCE.LOG in your PROGRAM DIRectory]. LOWBAUD.BBS - displays if user's baud rate is less than sysop's predefined lowest baud rate PRELOG.BBS - displays after making connection at acceptable baud rate. CLOSED.BBS - displays if user not in database and sysop running a closed bbs. OPEN.BBS - displays if user not in database and sysop running an open bbs. QUESNEW.BBS - displays if applicable and is user's 1st call (and an OPEN BBS) NEWUSER.BBS - displays if this is the user's first call (and an OPEN BBS) BIRTHDAY.BBS- displays if user's birthdate matches current date. ID#.BBS - displays if user's ID# matches. QSEC#.BBS - displays if user's security level matches # - once. SEC#.BBS - displays if user's security level matches # - always. HELLO1.BBS - displays if exists. HELLO2.BBS - displays if exists. HELLO3.BBS - displays if exists. BULLETIN.BBS- reported if changed since last logon, but not displayed. NEWSLTR.BBS - reported if changed since last logon, but not displayed. MAINMENU.BBS- if exists. . . QUOTES.BBS - Ending quote from this file is presented at logoff. The quote number sent is equal to: (NUMBER OF TIMES CALLER CALLED) MOD (NUMBER OF QUOTES) GOODBYE.BBS - if exists. This would be a good place to place MILC command @Wx (Wait x miliseconds) in order to give your modem a chance to empty its buffer (send) to the remote modem before finally disconnecting. @W2000 (wait 2 seconds) is usually sufficient. NOTE: Whenever Magnum can't open or display a file, it will send an informational message to the console (if you're snooping on someone): << SYSOP NOTE: File "filename" Not Found >> The remote user will never see this message, it's merely an informational message. You'll see these messages when you log on locally via the console as well. This message does not indicate an error, it merely indicates that the file didn't exist. For example, the HELLOx.BBS files are optional, and this message will display for each one of those files not found - this is normal. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank Running MAGNUM BBS Page 3-1 Starting MAGNUM BBS for the First Time Rather than go into the detail about the various .BBS and .SCR files, you can use the ones supplied for now and tailor them to your own liking later on. This way you can start your BBS now - not after hours of editing the .BBS files. Make sure you are in the subdirectory known as PGM_DIR. If you've used the MAGINST.EXE installation program, it will be d:\MAGNUM\PGM_DIR (where 'd:' is the drive letter Magnum BBS was installed on). IMPORTANT: ---> Just a reminder that this document assumes the 4-node version of Magnum, in which case node 4 (ie: STARTUP.4 and MBBSINIT.4) comprise your local console node. If you have the 2-node version, node 2 is your local console node. If you have the 9-node version, node 9 is your local console node. If you have the 33-node version, node 33 is your local console node, etc! For OS/2 1.x Users >>> FOR OS/2 1.x <<< USERS: If you have a PS/2, the COM02.SYS device driver will support up to 3 communications ports, otherwise the COM01.SYS device driver (for non-PS/2 machines) will support 2 communications ports. For OS/2 2.x Users >>> FOR OS/2 2.x <<< USERS: If you have a PS/2, the COM.SYS device driver will support up to 4 communications ports, otherwise 3 ports. Note that IBM's COM.SYS driver that comes with the OS is not very reliable, and can cause system slowdown. WE HIGHLY RECOMMEND DOWNLOADING 3RD-PARTY DRIVERS FROM OUR BBS. AS OF THIS WRITING, THE FILENAME IS SIOxxx.ZIP (xxx is the version number) AND IS IN OUR FILEBASE 0. USE THESE DRIVERS INSTEAD OF IBM'S!! The latest filename of the SIOxxx.ZIP file is available in our BBS info when you log on. FOR ALL USERS: >>> FOR ALL <<< USERS: If you're using a Digiboard or Artic card (intelligent communications coprocessor cards), you must obtain the OS/2 device driver for this card from Digiboard, or from Quadron (if you're using the Artic Card). These cards can provide support for up to 32 serial ports on one machine! NOTES: Prior to starting your BBS, you should modify your PATH statement (in your CONFIG.SYS file) to include your PGM_DIR, EXT_DIR, and RJE_DIR directory paths. It might also be a good idea for you to create a .CMD file to set these paths and to start MBBS.EXE automatically (from the system STARTUP.CMD file) in the event of a power failure - this way, the system will restart when the power returns. Magnum only opens nodes provided both the following criteria are met: 1) An MBBSINIT.x file exists for comport x, and 2) the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 3-2 Running MAGNUM BBS Starting MAGNUM BBS for the First Time MBBSINIT.x file was "compiled" from its STARTUP.x file with the ACTIVE parm set to Y. If either of these cases is false, the node will not be used. For example, if your STARTUP.2 file names COM2 as the DEVICENAME, but the ACTIVE parm is set to N (inactive), then COM2 will be available for other programs since Magnum will not be using it. At this point you should be in your PGM_DIR and you can start MAGNUM by entering MBBS on the command line (you may have already done this after the installation program finished). Any MBBSINIT.x file found by MAGNUM with the ACTIVE parm set to Y will result in MAGNUM opening the comport for that node and sending the initialization strings to the modem. Any MBBSINIT file with the ACTIVE parm set to N (and any MBBSINIT file NOT found) will result in Magnum not using the comport for those particular node(s) and will leave those comports free to be used by other programs. After initialization, you will do a local logon by typing the following: * LOGON Shortly after you hit the '*' character, it will appear next to the "Command=>" prompt. To start a command, you either need to start with the '*' character or the node number. In the case of local logon, you need to start with the '*' character. Before you hit the '*' character, MAGNUM was checking the comports for incoming calls. Once you hit the '*' or node number (1, 2, etc) - MAGNUM immediately stops checking for incoming calls and accepts what you have to type at the "Command=>" prompt. MAGNUM always assumes that if you're typing something at the "Command=>" prompt that it's of very high priority, so it stops what it's doing (checking for incoming calls) until you've entered a command and it finishes processing that command. The syntax of commands are always "X COMMAND" where X is an asterisk or digit - remember to always leave one space between the X and the COMMAND. After you've entered the "* LOGON" command, MAGNUM will call MSESSION.EXE to run your session. You are a new user at this point since there is no entry in the user database for you (or anyone else for that matter). Once you are prompted with the "LOGIN" prompt, enter your First Name exactly the way it appeared in your STARTUP file for your console node and press enter. Do the same with middlename and lastname - these must match the config file exactly! Once it matches, MAGNUM will welcome you as Sysop and make you go through the "new user logon procedure". If per chance someone has called your BBS prior to you logging on for the first time, they will get a "system not initialized" message and be automatically logged off. You (as sysop) must have an ID number of /0 (read as slash-zero). After you complete the new user logon procedure, you can now go into the sysop section and modify your parameters to whatever parms you wish. Once in the sysop section, choose the User area. Your profile should come up on the screen. Simply enter any fieldname you wish to change and hit enter - MAGNUM will then prompt you for the new value of that field. Everything else in the user area of the sysop section is self explanatory but we'll go into more detail on that later on. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Running MAGNUM BBS Page 3-3 Starting MAGNUM BBS for the First Time IMPORTANT: When online locally, the up and down arrow keys, and the PgUp and PgDn keys have special meaning. These keys are accepted at any prompt, and you should use extreme caution with these keys, as they change the priority of your local session. Anytime you're looged onto the local console, you can increase/decrease the priority of your local session with the following keys: PgUp - Increases Priority Class by 1 PgDn - Decreases Priority Class by 1 UpArrow - Increases Priority Level (within a class) by 1 DownArrow - Decreases Priority Level (within a class) by 1 These keys are recognized at any system prompt, but will not be recognized during message entry or chat modes. CAUTION: Setting your priority too high can cause other online sessions to "freeze" and file xfers on other sessions to "time out" (fail)! Try avoiding Class 3 altogether! There are 3 Priority Classes (1-3), the higher the class, the higher the priority. Within each class, there are 32 levels (0-31), the higher the level, the higher the priority within that class. Class 1 is "Idle Time", Class 2 is "Regular", and Class 3 is "Time Critical". If you haven't supplied your own values to the PRTY_CLASS and PRTY_LEVEL keywords in your STARTUP.x file(s), the default is class 2, level 0 for the console node; class 2, level 10 for all other nodes. when running locally, OS/2 gives a boost to the foreground session. Keep in mind that since you'll be running your local logon in the foreground, the higher the priority you give to your session, the slower the remote sessions will become because OS/2 is granting more processing time to your local session. After pressing any of the above 4 keys, Magnum will display an informational message similar to the following: Priority: Class=1, Level=31 Although this informational display sort of "messes up" the nice system prompt from where you were at, the prompt is unaware of any changes and still expects normal input as though nothing had happened. If you press any of the 4 keys too many times in succession, the informational messages sent with each keypress can cause the original prompt to scroll off the screen, so remember where you left off! This will become clearer to you as you use these realtime priority setting keys. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 3-4 Running MAGNUM BBS Starting Your FILES Database Now that you're on the system, it is ready for use by others! One of the first things that a sysop usually does is to add files to the file section. There are several ways to do this: 1) Upload them via remote modem/computer; 2) Manually place the files into the proper subdirectories you've set up and then use the Sysop section (file maintenance) to add them; 3) If you're logged on locally, go into the [F]ile section and choose [U]pload - as long as you've logged on locally (from the Console), the actual file transfer (no matter which one you choose) will prompt you for the source of the file and will perform a local "copy" of the file. For example, if you had a file on diskette in drive A and wanted to get it into the files database, supply the name of the file (drive, path, etc) and Magnum will copy it from drive A to the proper subdirectory - this simulates an upload. 4) If you are converting from another BBS system, and you know the record layout of its file database, you may be able to write a conversion program. We supply the layout of our databases in a file entitled MAGNUM.H located on your distribution diskette. 5) Use the MAGFILE.EXE program (and optionally, the MAGDRIVE.EXE program) explained next. MAGNUM allows an optional message to be associated with each file. This optional message can be up to 150 lines of text in length. Other than doing an upload from a remote computer, MAGNUM will let you create or modify any message for a file through the file menu's "[C]hange" command. On uploads of files in .ZIP format (a popular compression method used by PKWare), you can add a customized "zip file comment" to all uploads. See Chapter 2 (EXTERNAL DIRECTORY) for more information. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Running MAGNUM BBS Page 3-5 The MAGFILE.EXE Program (bulk file add) The MAGFILE.EXE Program (bulk file add) NOTE: MAGFILE.EXE is included in the DEMO version of Magnum, however, 128 file entries is the maximum the file database will hold in the demo release. The commercial release has a maximum of over 2 billion entries. By popular demand, many Sysops have asked for a way to get an entire directory into their FILE database(s) without having to manually go through the motions of 'uploading' the individual files. We bring you MAGFILE.EXE, which can do just that! It can add entire directories to any particular FileBase and any file area of any FileBase. One major use for this program is for when you need to deal with CD-ROM disks. To add an entire directory of files you must first create an ASCII text file containing the list of the files in the directory you wish to add. This can easily be accomplished on the OS/2 command line with (assume G:\SOMEDIR\DIR1): DIR G:\SOMEDIR\DIR1 >MAGDIR.LST the output of the DIR command has now been written to the MAGDIR.LST file. Next, edit the file, stripping out any directory names or any other text lines which don't contain valid filenames and sizes. Next, you will need to place 7 keywords and parameters at the top of the file (each on a line of its own). The 8th keyword (#PASSWORD:) and its parameter is optional. By way of example: #INIT: D:\MAGNUM\PGM_DIR\MBBSINIT.1 #BASE: 5 #AREA: C #NAME: 41-52 #SIZE: 18-26 #DESC: ** From CD-ROM \SOURCE\C\SAMPLES #CDROM: F #PASSWORD: where #INIT: Defines the filespec to one of your MBBSINIT.x files. #BASE: Defines which FileBase to add these files to. If you do not have the Extended FileBase module, this parm should be 0. #AREA: Defines the FileArea (of FileBase) to assign these files to. #NAME: Defines column positions filenames are in (FAT FORMAT ONLY). #SIZE: Defines column positions in which the file sizes appear. #DESC: This will be the description line added to each of the files. #CDROM: Optional! Defines the drive letter of CD-ROM drive Do NOT supply a parameter if not using a CD-ROM drive!! #PASSWORD: Lines starting with the ! or ; characters are ignored (comment lines). Optionally, the #DESC: parm can also define column positions in case you wish to manually provide a description for each file. Each text line can be up to 200 characters in length. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 3-6 Running MAGNUM BBS The MAGFILE.EXE Program (bulk file add) Save the changes, then run MAGFILE.EXE as follows: MAGFILE.EXE MAGDIR.LST When the program completes successfully, your files have been added to the FileBase specified in the #BASE parameter. If you execute MAGFILE.EXE without any parameter (ie: just MAGFILE.EXE and no filename), then the above instructions will appear on your screen. And don't forget to change your STARTUP.x file(s) for FileBase 0, or run your FILEBASE.EXE program (for extended FileBases) to accurately indicate the proper directory paths for the BASE and AREA parms you supplied above. Take note that although the 7 keywords and their parameters need to occupy the first 7 text lines, any of these keywords can re-appear anyplace else in the file with different parameters. This will allow you to change the file area or the FileBase or desc fields midstream. The changes take place from that point on, or until another change is encountered. Also note that if your FileBase already exists (ie: FILE.DAT for example), the new records will be appended (added) to the database, otherwise the program will create the database. Note that if the #PASSWORD: keyword is used, a blank parameter (absence of a parameter) turns off password protection. The presence of a parameter (a password) provides passowrd protection to ALL files following this keyword until the end of the file or until a #PASSWORD: keyword with a blank parameter is encountered to turn off pasword protection. You may have as many #PASSWORD: keyword/parameter statements as you wish as long as each is on its own separate text line. NOTE: This program does NOT check your existing FileBase for duplicate names (ie: names already in the database which may also appear within your directory list). Remember, duplicate filenames are fine as long as they're in different FileBases, but duplicate filenames in the same FileBase won't work as you might like them to. Most file operations in Magnum work on the first matching file! To get to a file with a duplicate name, use the #nnnn method (instead of the filename) when answering a filename prompt while online. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Running MAGNUM BBS Page 3-7 The MAGDRIVE.EXE Program (CD-ROM Support) The MAGDRIVE.EXE Program (CD-ROM Support) NOTE: MAGDRIVE.EXE is included in the DEMO version of Magnum, however, 128 file entries is the maximum the file database will hold in the demo release. The commercial release has a maximum of over 2 billion entries. This program is a simple program to run. Simply run it with the drive letter of your CD-ROM drive as the parameter to this program. For example, if the drive letter of (one of your) CD-ROM drive is F, then run the program as: MAGDRIVE F The output of this program is placed in a file d.DIR (where 'd' is the drive letter you specified)... in the above example, the output file would be F.DIR The resultant d.DIR file is an ASCII text file of all of the files in each and every subdirectory of that drive! Edit the d.DIR file with your favorite text editor according to the rules of the MAGFILE.EXE program described above, but DO NOT remove any of the statements starting with PATH[ in column 1. The d.DIR has already filled in the #CDROM, #NAME, and #SIZE fields for you. When you've finished editing the file, run it as the parameter to the MAGFILE.EXE program. The #BASE and #AREA parameters will determine which area of which FileBase the CD-ROM files will be stored in. The files will always remain on your CD-ROM drive. Unlike other BBS software, Magnum has no need for copying any files from your CD-ROM drive to someplace else in order to [A]ccess, [D]ownload, or perform any other function. Although there may be litterally thousands of subdirectories on a particular CD-ROM disk, as far as the online user logged onto Magnum is concerned, they're all in File Area x of FileBase y (where x was the parm to your AREA keyword in the d.DIR file, and y was the parm to your BASE keyword in d.DIR). Once you've run the MAGFILE.EXE program against the d.DIR file, you may delete the d.DIR file, all information is now in Magnum's File Database(s). Note that there may be many duplicate filenames on any given CD-ROM disk. A popular name which may occur in many subdirectories is READ.ME. If the online user specifies a filename (to a filename prompt), Magnum will always use the first matching entry. To get to the particular file you have in mind, always use the #nnnnn method of file entry. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank Customizing MAGNUM - Display Files/MILC Commands Page 4-1 Intro The end of Chapter 2 lists the order of display files. This chapter will explain the embedded MILC (Magnum Interpreted Language Commands) which can be a part of each of your display files. MILC is a very powerful BBS language. Before we go into that, it should be pointed out that anytime MAGNUM displays a file, it first looks to see if the user who's going to view the file has their color settings on. If yes, it looks for whatever filename that's about to be displayed with an extension of .SCR - if it finds it, it displays it - otherwise, it displays the filename with an extension of .BBS instead. Files with an extension of .SCR are meant for color users only - you needn't have any .SCR files to have color, but basically your .SCR files are the ones with the fancy ANSI escape sequences in them to do things like motion, cursor positioning, etc. Whether you use .SCR files or not, MAGNUM has provided a way for you to use color in your .BBS files and present the color sequences to those using color, or ignore them for those not using color - all transparent to the user viewing the files. MAGNUM's MILC language lets you take advantage of advanced display techniques such as mathematics, string logic, IF, inclusion of other files (with options), branch to anywhere in the file, perform I/O, screen control (including color), give the illusion of a customized display to the current user, and multitudes more! Embedded MILC commands in Display Files Display files typically have extensions of .BBS or .SCR and display on the remote user's terminal. The difference between .SCR and .BBS files is .SCR files are searched for and displayed ONLY if the remote user has his color setting set to YES. In the event that a .SCR file is not found, the corresponding .BBS file is displayed instead. .BBS files may also contain color, however, the color is via embedded MILC color commands which are executed only if the remote user has his color setting set to YES, otherwise the embedded color commands are ignored. Display files are not limited to .SCR or .BBS files. Every message (mail) entered on your system in the message section can also contain MILC commands (refer to the page #'s defining the MILC_CMDS field in the index). The MILC_CMDS field of each user's record defines which of the MILC commands are available for them to use in their messages. In the case of MILC commands appearing in messages, the commands which the originator of the message are allowed to use (not the reader) are governed by the originator's MILC_CMDS field. NOTE that the MILC command character (the character that denotes the start of a MILC command) may be (and usually is) different for message text than any other display file. The defaults (unless you change them in your STARTUP.n files) are '@' for all displayable files other than message text, and '^' for all message text. All display files (except PRELOG.bbs, LOWBAUD.bbs, CLOSED.bbs and OPEN.bbs) may contain embedded MILC commands. Numerous categories of MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-2 Customizing MAGNUM - Display Files/MILC Commands Intro commands exist, each beginning with the command character "@" (without the quotes). The above named exceptions may contain MILC commands which do NOT reference any USER-specific information because the user is not fully logged on at this time (ie: Magnum has no way of knowing their name or any other information about the user). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-3 Color Commands (@A) @A commands PURPOSE: Change colors for 'color users' -no effect on 'non-color users' FORMAT: @Ax Where 'x' is a 1 to 3 digit number ranging from 0 to 255. The @A commands are the ones that change the color attributes. Once a @A command is executed, that color will remain until the end of the file or until another @A command is executed. The following are the attribute values of 'x': @A0 - BLACK on BLACK @A8 - GRAY on BLACK @A1 - BLUE on BLACK @A9 - hi-intensity BLUE on BLACK @A2 - GREEN on BLACK @A10 - hi-intensity GREEN on BLACK @A3 - CYAN on BLACK @A11 - hi-intensity CYAN on BLACK @A4 - RED on BLACK @A12 - hi-intensity RED on BLACK @A5 - MAGENTA on BLACK @A13 - hi-intensity MAGENTA on BLACK @A6 - BROWN on BLACK @A14 - bright YELLOW on BLACK @A7 - WHITE on BLACK @A15 - hi-intensity WHITE on BLACK @A16 to @A31 - same as @A0 to @A15 but on BLUE background @A32 to @A47 - same as @A0 to @A15 but on GREEN background @A48 to @A63 - same as @A0 to @A15 but on CYAN background @A64 to @A79 - same as @A0 to @A15 but on RED background @A80 to @A95 - same as @A0 to @A15 but on MAGENTA background @A96 to @A111 - same as @A0 to @A15 but on BROWN background @A112 to @A127 - same as @A0 to @A15 but on WHITE background @A128 to @A255 - same as @A0 to @A127 but blinking (simply add 128 to any of the above for blinking) Example: @A2 You are a @A10New User@A2 and we welcome you aboard! this would print: "You are a New User and we welcome you aboard!" where then entire sentence is displayed in green except for "New User" which is displayed in hi-intensity green. If the remote user had his color settings set to NO, then the sentence would appear normally and all in one color (whatever color his CRT displays, and the @Ax commands are automatically removed). Notes: As with all '@' commands, the @Ax commands will not be displayed, but their effects will be displayed. The @A commands will have no effect if the user viewing any text containing these commands has their 'color' selection turned off - they will simply be stripped from the text and not executed. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-4 Customizing MAGNUM - Display Files/MILC Commands Branch (IF) Commands (@B) @B Commands PURPOSE: Branch conditionally or unconditionally to another part of the file FORMAT: @Bx(EXP); where 'x' is the label number to branch to (0 to 99), and EXP is the expression to be evaluated. If EXP (expression) is TRUE, the branch is taken, otherwise display continues. The @B command alters the display of a file. It can jump forward, backward, or not at all depending on the expression in parenthesis. NOTE: Please read about the @Z, @N, and @P commands and have a thorough understanding of them before attempting to read further. In order for a branch to take place, the following 2 conditions must be met: 1) The expression must be TRUE 2) The label must exist somewhere in the current file Let's say you have defined a label somewhere in your file as label # 5 (an embedded @P5 somewhere in the file). The label could be in a previous part of the file or in a forward part of the file (ie: anyplace). Since this is best learned by examples, lets start with a forced (unconditional) branch: @B5(0=0); [ NOTE: @B5; is identical to @B5(0=0); ] This would cause an unconditional branch to label 5 (@P5) since the expression (0=0) is true. The "=" sign means to compare the left parameter with the right parameter and if they are equal, the result is true. If the expression were (0=1) instead, then no branch would take place since 0 does not equal 1. This is the simplest of the branch instruction. The valid comparators are: = equal to > greater than < less than >= greater than or equal to <= less than or equal to != not equal to ~ If string2 is contained within string1 !~ If string2 NOT contained within string1 Using numeric variables (see the @N command), let's try a few more examples: @B5(N2=16); @B5(N2!=N12); MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-5 Branch (IF) Commands (@B) @B5(N4<N2); Note in all three examples the absence of any spaces. All branch commands MUST BE TERMINATED WITH THE ';' character (semicolon)! Using string variables (see the @Z command), let's try a few more examples: @B5(Z3=Z4); @B6(Z2!="John"); Note the use of Quotes to define a "hard-coded" string (as opposed to a variable string). The "hard-coded" string may contain embedded spaces within the surrounding quotes. NOTE: string comparisons are NOT case sensitive. This means that "John" is the same as "joHN". Now for a working example: @N1=0; This line is being displayed @P5 This line will be displayed twice @N1=(N1+1); @B5(N1=1); And now on to the next line Evaluating the above, the first @ command is @N1=0; which assigns 0 to the variable N1. The text "This line is being displayed" is displayed. Next, a label (@P5) is defined and the text "This line will be displayed twice" is displayed. After that, an arithmetic expression that increments variable N1 by 1 is encountered. N1 is increased by 1 and now contains the value 1. The branch command says to branch to label 5 (@P5) if N1 is equal to 1. Since the expression is TRUE, a branch is taken to @P5 and "This line will be displayed twice" is displayed again. N1 is again incremented by 1, leaving the value 2 in variable N1 as a result. The branch statement becomes false (N1 is now equal to 2, not 1) and the display continues with "And now on to the next line". To check if a string is contained within another string, lets suppose that the variable @Z1 contained "HAPPY NEW YEAR". If you wanted to check to see if "EAR" were contained within the string, you could do it as follows: @B5(Z1~"EAR"); EAR is not in @Z1; @P5 What this would do is check if string2 ("EAR") were contained in string1. If the result is TRUE, a branch would be taken to label @P5, otherwise no branch would be taken and processing would continue with displaying "EAR is not in HAPPY NEW YEAR". However, in this case, the comparision is TRUE and the branch would be taken to @P5, skipping over the display of "EAR is not in HAPPY NEW YEAR". NOTE: A forced (conditional) branch does not need the (EXP) part of the statement. For example, @B5; and @B5(0=0); are identical. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-6 Customizing MAGNUM - Display Files/MILC Commands Screen Control Commands (@C) @C Commands PURPOSE: Controls the screen/display FORMAT: @Cx where x is a numeric parm representing the control function The @C command controls the screen or display of a file. The parameters are 0 through 11 as follows: @C0 - NONSTOP. This is the same effect as the remote user answering 'N' to the "-- MORE -- [C]ont, [S]top, [N]onstop" prompt. @C1 - STOP, WAIT FOR KEYPRESS. This command stops the display and waits for the remote user to strike a key. Note that no prompt is given - you should supply your own prompt to let the remote user know that you are waiting for them to press a key. (ie: "Press any key ...@C1") @C2 - RESUME NORMAL DISPLAY. This command negates the @C0 command - it resumes normal prompting ("-- MORE --") when a full screen is displayed (and the remote user has their "MORE" prompts turned on). @C3 - BEGIN SKIP. This command is kind of like a comment that never gets shown. Everything following this command is skipped until a @C4 command is encountered. @C4 - END SKIP. This command negates the @C3 command. Normal Display and processing of text and commands resume when this command is encountered. @C5 - IGNORE COMMANDS. Similar to the BEGIN SKIP (@C3) command, this command turns off, or disables command processing. All commands that follow from this point on will be treated as text instead of commands (and thus displayed instead of processed). The @C6 command is the exception, which negates this command. @C6 - PROCESS COMMANDS. Negates @C5 command. When @C6 command is encountered, normal command processing will resume. @C7x - CHANGE COMMAND CHARACTER. This is the only command in the @C group of commands that takes another parameter. That parameter is a single character which tells the file display routines to use a different character to recognize commands with. For example, the command @C7% tells the file display functions that the '%' character is now the command character, not the '@' character. So, @C7^ makes the '^' character the command character from that point on, until another ^C7 command is issued to change it to another character. Use extreme caution in MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-7 Screen Control Commands (@C) selecting a command character - that character should only be used for commands and not text. @C8 - RESET LINECOUNT. This command resets the line counter used for the -More- prompt. This comes in handy after 'including' a file or branching to somewhere in the file where this would become necessary. @C9 - PRESS ENTER. This command prompts the remote user to press their ENTER (or C/R) key. The file display stops, the "PRESS ENTER ..." prompt appears, and the function waits until the remote user presses ENTER. @C10 - BREAK OFF. This command turns off the ability to break or stop display of a file with the <Ctrl-X> or the space bar. Although this command can appear anywhere in the file, a user can still stop the display if s/he does so before this command is processed. However, if @C10 is contained as the first 4 characters of the file, the command is guaranteed to take affect because Magnum will disallow a break during the first 4 characters of a file for this purpose. @C11 - BREAK ON. This command negates the @C10 command. @C12 - Ignore all text - process commands only. Ideal for large blocks of commands where CR/LF and spaces are not intended to display. Stays in this state until @C13 encountered. ** CAUTION: Be careful when using @B (branch) commands without issuing a @C13 to turn text display/processing back on again. @C13 - Negate @C12. @C14 - Turn off HIGHLIGHT. Ordinarily, reader display of @Z, @N, @O, and @U substitutions are highlighted. The @C14 command turns off this highlighting. NOTE: highlight is only active when the remote user's color setting is Y. @C15 - Negate @C14. @C16 - Terminate display of current file. @C17 - Log the user off! (be careful with this one!) Emulates a dropped carrier (disconnect). Sysop/Cosysop use only! @C18 - Clears the screen. If the user's color settings are set to YES, an ANSI "clear screen" escape sequence is sent, otherwise a FormFeed character (Ctrl-L) is sent. @C19 - forces an internal result code of FALSE (ie: file not found or file not displayed). An example of the use for MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-8 Customizing MAGNUM - Display Files/MILC Commands Screen Control Commands (@C) this command would be the following: You wish to display something using your external menu(s) (ie: FILEMENU.BBS, MSGMENU.BBS, etc), but also want Magnum to dynamically generate the menu. Magnum only generates an internally-built dynamic menu if the xxxxMENU.BBS (or xxxxMENU.SCR) file doesn't exist. Within this file, you can now issue the @C19 command, which will generate an internal result code indicating that the file was not found - even though the file is displayed. This essentially "fools" the menu routines into thinking that the menu file was not found and will therefore generate the internal menu. This MILC command is ignored if it appears within a message file. This MILC command does not terminate the display of a file, it merely sets the internal result code. NOTE: The external menu file is only displayed upon entrance to the menu. After that, the internal menu will be dynamically generated each time the menu needs re-generation. If the menu is exited, then returned to (ie: if in FILE menu, then the menu will be re-generated if they choose [Q]uit, and then re-enter the FILE section anytime afterward). @C20 - Make the length of the string variable in @Z0 equal to the length of the variable in @N0. The following gets the user's first name into variable @z0, makes the length exactly 10 characters, then displays it: @z0=u3; @n0=10; @c20; @z0; @C21 - Disable Menu Prompts. For those who are doing their own prompting via external menus and stacking (@Sx) menu commands. By disabling the menu prompts with this new MILC command, the dynamically generated menu prompt (which is displayed after displaying the external menu) will be supressed until a @C22 command is issued. This command applies to ALL menus (ie: main, rje, msg, file, sysop) but not to submenus (such as the 'read messages submenu'). NOTE: Disabling menu prompts also disables the CR/LF sent after displaying an external menu, as well as the date/time and minutes remaining information normally displayed prior to the prompt. @C22 - Enable Menu Prompts. Negates @C21. @C23 - Same as @C21 but only ONCE after this command is issued. Unlike the @C21 which disables menu prompts until a @C22 is issued, this command will disable the next menu prompt and reactivate prompts afterward. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-9 Screen Control Commands (@C) @C24 - Store current screen (actually the last 2,000 bytes displayed) Can hold up to 999 screens, thus can be called up to 999 times before calling @C25 (restore). If the number of calls exceeds 999 without doing a restore the function simply returns with no action and no error message or warning. @C25 - Restore last screen (actually the last 2,000 bytes stored). If called more than the number of times @C24 (store) has been called, the function simply returns with no action and no error message or warning. @C26 - Disable Mandatory Response for @Zn input. This will enable a user to simply press ENTER without having to enter a mandatory response to any input requested by @Zn(xx); or by @Zn('abc'); Note: If the user presses ENTER with no other response, or enters a blank (one or more spaces with no other chars) response, then the original contents of @Zn will be retained. This way, you may provide for a default response. Note that @C26 applies only to string input (ie: @Zn(xx); and @Zn('abc'); but NOT to numeric @Nn input requests). In the case of @Zn('abc'); where a single character input response is requested (ie: a, b or c), then make certain that if you use @C26, that you place a valid input response in @Zn prior to asking for input - if you don't, the default response will be the first char of the 'abc' string (in this case, A). @C27 - Enable Mandatory Response for @Z input (the default). Negates @C26. Note that C26/C27 are system-wide and NOT initialized with each new display file (ie: if you specify @C26 in ANY display file, then ALL @Zn input commands will assume non-mandatory responses! @C27 is the default at session startup. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-10 Customizing MAGNUM - Display Files/MILC Commands Date Conversion Function (@D) @D Command PURPOSE: Converts a partial date to a 10-character date string (MM/DD/YYYY or DD.MM.YYYY depending on user's date format). FORMAT: @Dx When prompting a user for a date, they may enter a date in a format such as M/D, MM/D, M/DD, MM/DD, MM/DD/Y, MM/DD/YY, etc (or it's European equivalent entry). The @Dx command simply converts a partial date to a 10-character date string. The 'x' tells the @D command which @Zx variable holds the partial date string. In the following example: Enter Starting Date => @Z5(10); @D5 The @Z5(10); prompts the user for a string of up to 10 characters which will be placed in variable @Z5. The @D5 command converts the date in variable @Z5 to a 10-character date string. For example, if the user entered "3/1" in response to the date prompt, the @D5 statement would convert the string to "03/01/1990" (or whatever the CURRENT YEAR happens to be). If the user has specified European date formats in their Environment settings, the date would be converted to 01.03.1990 instead. In the event a user enters garbage in response to the prompt (ie: an invalid date or invalid partial date), the @Dx function will convert the string in @Zx to "01/01/1980" (or 01.01.1980). Users can enter dates in either MM/DD/YYYY or DD.MM.YYYY formats. If the conversion routine called by @Dx sees the '/' character, it assumes the date has been entered in US date format, otherwise if it sees the '.' character, it assumes the date has been entered in European date format. If the user entered the date in US format but had their default settings to European, the date in @Zx would also be converted to European date format. Likewise, if the user entered the date in European format but had their default settings to US, the date in @Zx would also be converted to US date format. As a result, any external programs you write which accept a 10-character date as input, must also be able to accept the date in either US or European format. Conversion from one format to another is not very difficult at all if the date is always supplied as a 10-character string. For example, in the 'C' language, the following functions would perform your conversions: date2US(datestring) /* Converts from European or US date */ char *datestring; /* format to US */ { char c; if(datestring[2]=='/') /* Already in US format - return */ return; if(datestring[2]=='.') /* If in European format, do conversion */ { c=datestring[0]; datestring[0]=datestring[3]; MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-11 Date Conversion Function (@D) datestring[3]=c; c=datestring[1]; datestring[1]=datestring[4]; datestring[4]=c; datestring[2]=datestring[5]='/'; } } date2European(datestring) /* Converts European or US to European */ char *datestring; { char c; if(datestring[2]=='.') /* Already in European format - return */ return; if(datestring[2]=='/') /* If in US format, do conversion */ { c=datestring[0]; datestring[0]=datestring[3]; datestring[3]=c; c=datestring[1]; datestring[1]=datestring[4]; datestring[4]=c; datestring[2]=datestring[5]='.'; } } These routines are only examples, but are very fast because there's no function calls made and all we're doing is manipulating characters! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-12 Customizing MAGNUM - Display Files/MILC Commands External and RJE Program Execution Commands (@E) @E Command PURPOSE: Starts an External (child process or door), or RJE (independent process) program. FORMAT: @Ex @E0: @E0 - Executes an external program (without using the [D]oor menu). Works the same as [D]oors (child processes) - the external process being called must be in the EXTernal DIRectory. The variable @Z0 holds the program name, @Z1 holds any parameters needed by the program, @N0 tells how the pgm's I/O is to be handled. When the external program finishes executing, the result code of the program will be placed in MILC variable @N1. See CHILDREN.BBS in the "Creating Subdirectories" portion of the user's manual. See Chapter 2, CHILDREN.BBS of EXTERNAL DIRectory for more information. CAUTION: DO NOT ALLOW YOUR USERS ACCESS TO THIS COMMAND!! MAKE SURE IT DOES NOT APPEAR IN THE "MILC_CMDS=" OF ANY USER'S RECORD!! IF A USER HAS ACCESS TO THIS COMMAND, THEY COULD TAKE CONTROL OF YOUR ENTIRE SYSTEM AND DO ANYTHING THEY WANT!! @E1: @E1 - Similar to MILC variable @E0, except the process is started as an RJE task (detached and running in the background), and is expected to be found in your RJE DIRectory. The process must NOT read from stdin, or write to stdout or stderr (it actually can write to stdout/stderr but output will be lost!), and must NOT require any keyboard or mouse input or screen output (redirection of stdin, stdout and stderr is ok), otherwise all I/O should be to and from FILES only, not devices! If the print spooler is enabled, this is probably ok. As with the MILC @E0 command, the required @Z0 and @Z1 parameters are the same, but the @N0 and @N1 parameters are different: @N0 should contain the Priority CLASS and LEVEL of the process: NO CHANGE IN CLASS: 1 = lowest priority level of the class 31 = highest priority level of the class CLASS 1 (Idle Time) 100 = lowest priority level of "Idle" Class (class 1, level 0) 131 = highest priority level of "Idle" Class (class 1, level 31) CLASS 2 (Regular) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-13 External and RJE Program Execution Commands (@E) 200 = lowest priority lvl of "Regular" Class (class 2, lvl 0) 231 = highest priority lvl of "Regular" Class (class 2, lvl 31) CLASS 3 (Time Critical) 300 = lowest priority lvl of "Critical" Class (class 3, lvl 0) 331 = highest priority lvl of "Critical" Class (class 3, lvl 31) For example, if you want your RJE program to run in the "Idle Time" class, with a priority level of 15 (the middle of the class), you would assign the value of 115 to variable @N1 as follows: @N0=115; If you don't want to bother with setting priority levels, simply assign an invalid number to variable @N0 (ie: @N0=99;), which will force Magnum to assume a default of 125 (class 1, level 25). Valid numbers are: 1 to 31, 100 to 131, 200 to 231, and 300 to 331. The contents of MILC variable @N1 tells Magnum whether to notify the user in the event the RJE job completes while they're still online. If @N1 is zero, no notification will take place, otherwise if @N1 is 1 (nonzero), Magnum will notify the user of the completed RJE job in the event that the job completes before the user's session is over. Once the process has been started, the values in MILC variables @Z1 and @N1 will be overwritten with information about the RJE process. Variable @Z1 will contain a 10-character string which is the name Magnum assigns to the job, and variable @N1 will contain the process's PID (Process Identification as used by OS/2). If the PID (@N1) contains the value of 0 after starting the job, then this indicates that the job was unable to be started, otherwise if non-zero, the job started successfully. NOTES ABOUT @Ex COMMANDS: In many cases, you'll want (or need) to run a .CMD file instead of a single .EXE program. In order to run .CMD files, you need to specify CMD.EXE as the program to run, and give it a parameter of "/c xxxxxxxx.cmd" (where 'xxxxxxxx' is the name of your .CMD file. For example, if you wanted to run a .CMD file called RUN.CMD, your @Zx MILC commands would be set up as follows: @z0="cmd.exe"; @z1="/c run.cmd"; Of course, you could also have supplied parameters to pass to the .CMD file as well: @z0="cmd.exe"; @z1="/c run.cmd parm1 parm2"; It's important to remember the "/c " as the first thing in the @z1 string because it tells OS/2 to terminate the "cmd.exe" program MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-14 Customizing MAGNUM - Display Files/MILC Commands External and RJE Program Execution Commands (@E) when your .CMD file finishes executing. *** IMPORTANT: IF YOU DON'T SUPPLY THE "/c " PARAMETER AS THE FIRST THING IN @Z1 WHEN "CMD.EXE" IS THE PROGRAM IN @Z0, THEN CMD.EXE WILL NOT END!!! THE REMOTE USER WILL HAVE THE CMD.EXE COMMAND PROMPT (AND YOUR ENTIRE SYSTEM) AVAILABLE FOR THEM TO DO WHATEVER THEY WANT! CAUTION: DO NOT ALLOW YOUR USERS ACCESS TO @Ex COMMANDS!! MAKE SURE E DOES NOT APPEAR IN THE "MILC_CMDS=" OF ANY USER'S RECORD!! IF A USER HAS ACCESS TO THIS COMMAND, THEY COULD TAKE CONTROL OF YOUR ENTIRE SYSTEM AND DO ANYTHING THEY WANT!! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-15 Miscellaneous @E commands Miscellaneous @E commands PURPOSE: To perform certain functions which should only be available to the Sysop. FORMAT: @Ex @E2 - Send File. This command transmits a file that is NOT in the file database to the remote caller. @Z0 holds the filename. Upon return of the transmission, variable @N0 holds the result (1=success, 0=failure). If the user does not have a default file xfer protocol chosen, s/he will be prompted for one. The function also determines whether the caller is on remotely, locally or via pipe module and acts accordingly. This function provides a means of file xfer unrelated to the BBS. No upload/download ratios are checked, remaining time is not checked, the file is not counted as a download, etc. Example: @Z0="d:\magnum\somefile.zip"; @E2 @B1(N0=1); File Transmission Unsuccessful! @C16 @P1 File Transmission Successful! The Sysop can use this within a message to point to a file to download by the reader (without having to attach the file to a message). NOTE: @E2 command is NOT available in the DEMO configuration. @E3 - Receive File. This command receives a file from the remote caller and does NOT update the file database. @Z0 holds the filename. Upon return of the function, variable @N0 holds the result (1=success, 0=failure). If the user does not have a default file xfer protocol chosen, s/he will be prompted for one. Note that if the file exists, the function will delete the file prior to receiving it. The function also deletes the file if the file transfer fails. The function also determines whether the caller is on remotely, locally or via pipe module and acts accordingly. This function provides a means of file xfer unrelated to the BBS. No upload credit is given, remaining time is not checked, the file is not integrity checked, upload/download ratio not adjusted, etc. Example: @Z0="d:\magnum\somefile.zip"; @E3 @B1(N0=1); File Reception Unsuccessful! @C16 @P1 File Received Successfully! NOTE: @E3 command is NOT available in the DEMO configuration. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-16 Customizing MAGNUM - Display Files/MILC Commands Miscellaneous @E commands @E4 - Places name of "response file" in @Z0. The "response file" is the name of the file that any @Zx(""); or @Nx(""); requests will be written to. @E5 - Turn off "response file" header. This supresses the header Magnum writes to the "response file" before logging responses (ie: user's name, id, phone number, date & time, etc). NOTEs: - This works only on the currently-displaying file! If you "include" a file, you must also issue this command from the included file if you want supression. - This command should be issued prior to writing (ie: prior to issuing any @Zx(""); or @Nx(""); commands. @E6 - Override "response filename" with that of the one in MILC variable @Z0. For example, to create a DOOR.SYS file, you would assign the name of the file in @Z0 (example: @Z0="d:\magnum\ext_dir\door.sys";), then you would issue the @E6 command. Make certain to also issue the @E5 command to alert Magnum to NOT write the response file header! @E7 - Open the (ASCII) file in @Z0 for Reading. Upon successful open, @N0 will contain 0, otherwise an error number. If you open another file with @E7 prior to closing an existing opened file, it will close the existing file first. @E8 - Read one text line (up to 100 chars) of the file opened with @E7 (above) into @Z0. The number in @N0 will indicate how many bytes were read. If 0, the file is automatically closed. Magnum will insure that each line read has a CR/LF pair at the end, therefore any blank lines read will have at least 2 bytes. The purpose for the @E7, @E8 and @E9 commands is to have the capaibility of reading an ASCII text file and scanning for a match on a certain keyword with the @Bx(@Z0~"keyword"); statement. As a rough example, here's a small example file which only displays those text lines which contain the word "execute". @z0="d:\mydir\read.me"; @c12 @e7 @b99(n0>0); Open was successful! @p0 @e8 @b99(n0=0); @b1(z0~"execute"); @b0; @p1 @z0; @b0; @e9 @p99 @E9 - Close the file opened with @E7 (above). For examples on @E4 - @E9, see the file MAKEDOOR.BBS with this distribution; it demonstrates how to make a DOOR.SYS equivalent for those external door programs which depend on this file (ie: DOS 'doors' such as TradeWars is being ported to OS/2). NOTE: External 'door' programs such as TradeWars which make use of a DOOR.SYS-equivalent file expect their dates in U.S. date format; Magnum writes dates in either U.S. or in European date MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-17 Miscellaneous @E commands format depending on what the user's default date format is; you may have to notify the user to change to U.S. date format! The MAKEDOOR.BBS file was placed into your EXT DIR with this installation. If you plan on using it, you will need to modify part of it to reflect things about your system - see the comments within that file. @E10 - Disable output. Suspend all output to modem or screen. All output sent following this command will be discarded (ignored) until the @E11 command is issued. @E11 - Enable output. Negates @E10, resumes output. @E12 - Disable Timer. This command comes in handy when someone is about to run out of time on your system, and you want them to have more time. For example, suppose you run a subscription service or offer an 'online order' menu in which users can place credit card orders. We've seen users get logged off by Magnum because they ran out of time, yet they were in the middle of trying to place on online order! When you use the new @E12 command, this will no longer happen. The timer is temporarily suspended with this command, until you issue an @E13 command to reactivate the timer. NOTE: If you forget to negate this command with the @E13 command, the timer will not reactivate! Therefore, we've built in a safety measure. If you use this command, Magnum will automatically issue an @E13 command internally after a period of 5 minutes. @E13 - Enable Timer. Negates @E12 (ie: re-activates timer). @E14 - ReOpen FileBase 0 (main) @E15 - ReOpen MsgBase 0 (main) NOTE: MILC commands @E14 and @E15 are designed to be used after calling calling a .MEX program with the @E0 command (do not use these if calling the .MEX program with the @E1 command). When a .MEX program is called to update a user's file or msg access areas online, the update takes place immediately, however, the information within the file & msg menus don't reflect the change until next logon. Use of the new @E14 and @E15 commands will refresh the access areas to the menus. @E16 - Disable Timer. Like @E12 but no automatic timer re-enable. You must issue the @E13 command to re-enable the timer if you disabled it with this new @E16 command. @E17 - Strips CR/LF from text in @Z0 - useful for read operations performed with @E8. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-18 Customizing MAGNUM - Display Files/MILC Commands Additional @E commands for 'Extended FileBase and MsgBase' Additional @E commands for 'Extended FileBase and MsgBase' PURPOSE: To provide processing power for those Sysops using optional 'Extended FileBase' and/or 'Extended MessageBase' modules. FORMAT: @Ex @E80 - Prompts User to choose new FileBase (0-255). New FileBase chosen is also returned in @N0;. Requires 'Extended FileBase'. @E81 - Changes FileBase to value (0-255) in @N1;. New FileBase is also returned in @N0;. At the end of the @E81 command, if variables @N0 and @N1 are unequal, no change took place. Requires 'Extended FileBase'. @E82 - Prompts User to choose new MsgBase (0-255). New MsgBase chosen is also returned in @N0;. Requires 'Extended MsgBase'. NOTE: This command is ignored if part of a Message! @E83 - Changes MsgBase to value (0-255) in @N1;. New MsgBase is also returned in @N0;. At the end of the @E83 command, if variables @N0 and @N1 are unequal, no change took place. Requires 'Extended MsgBase'. NOTE: This command is ignored if part of a Message! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-19 Include File Commands (@I) @I Command PURPOSE: Includes (displays/processes) another display file within the current display file. FORMAT: @Ix"d:\path\filespec" | @Ix@Zy The INCLUDE command simply halts display of the currently displaying file, processes the 'included' file (and any 'included' files it may have), then returns to either continue displaying the current file or ending the display of the current file, depending on parameter 'x'. 'x' can be one of 0 to 4: 0 = Terminate the current file after the include. Inheritance OFF. 1 = Continue the current file after the include. Inheritance OFF. 2 = Terminate the current file after the include. Inheritance ON. 3 = Continue the current file after the include. Inheritance ON. 4 = Same as 3 but the alterations to @Zx and @Nx variables by the 'included' file will remain upon return. Inheritance OFF means that the included file will have its own @Nx (numeric) and @Zx (string) variables. Inheritance ON means that the included file will inherit the @Nx and @Zx variables of the calling file - upon return to the calling file, the @Nx and @Zx variables will be restored to where they were prior to the 'include' if 'x' was 3, otherwise if 'x' was 4, the @Nx and @Zx variables will retain any changes made by the 'included' file. NOTE: Please have a thorough understanding of the @N and @Z commands before continuing! This powerful command is the entire basis for Bulletins, Questionairres, Newsletters or any other kind of file offering a menu. An example Bulletin file (BULLETIN.BBS or BULLETIN.SCR) might look something like this: @P30 @c8 @a14BULLETIN MAIN MENU@a10 1 - What is MAGNUM BBS and who is Gilmore Systems, anyway? 2 - WOW! How can I get a copy of MAGNUM, What's the price? 3 - Info about becoming a purchasing MAGNUM BBS software. Q - Quit - return to BBS Choice => @z0('123Q'); @b1(z0="Q"); @z1=("c:\gs\com\1\bul_dir\bullet"+z0); @i1@z1 @b30(0=0); @P1 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-20 Customizing MAGNUM - Display Files/MILC Commands Include File Commands (@I) The file works like this: The @P30 defines a label. The @C8 resets the line counter (for the -More- prompt). The @A14 and @A10 commands change the color. All text is displayed. After "Choice => " is displayed, the @Z0 command restricts the user to choose one of 1,2,3 or Q. If the user chose Q, a branch is made to @P1 which is the end of the file. Otherwise, no branch is made and string variable @Z1 is assigned a partial filespec to which the user's choice ("1", "2", or "3") is concatenated (if the user chose "2" for example, @Z1 would contain "C:\GS\COM\1\BUL_DIR\BULLET2"). The next command 'includes' the file named in variable @Z1 without inheritance and continues with the next instruction after the 'included' file is finished displaying. The next instruction unconditionally branches to label @P30 to start the whole process over again. The above example used a @Zx (string) variable to contain the name of the file to be 'included'. Note that for less sophisticated menus, you could 'hard-code' the filename within quotes: @I0"c:\gs\com\1\bul_dir\bullet2" or @I0"c:\gs\com\1\bul_dir\bullet2.bbs". NOTES: 1) The variable @Z1 purposely was not given a filename extension. When no filename extension is given, the 'include' command will first look for the filename with an extension of ".SCR" if the user's color settings are set to YES. If not found, or if the user's color settings are set to NO, then it will look for the filename with an extension of ".BBS". If neither is found, the 'include' ends, returning back to the calling file. 2) DO NOT go beyond 3 to 4 levels of includes. In other words, for maximum safety, File A can include file B, which includes file C, which includes file D. Do not go beyond this point to a file E! 3) Note that unlike other '@' commands, when a @Zx variable contains the name of an 'included' file, the '@' (or current command character) is needed. In other words, @I1@Z4 is correct, while @I1Z4 is incorrect. With the power of the @I command, menus and submenus can be built to form a sophisticated Bulletin menu/system, Questionairre menu/system or Newsletter menu/system. When a caller logs on, the system will check to see if either BULLETIN.SCR (or BULLETIN.BBS), and NEWSLTR.SCR (or NEWSLTR.BBS) has a filedate later than the caller's last call. If true, the system will advise the caller that BULLETIN(s) or NEWSLETTER(s) have been updated since their last call (giving dates and times of updates). So remember that if you make a change to any of the 'included' files, you must change the date of the BULLETIN.SCR (or BULLETIN.BBS), or NEWSLTR.SCR (or NEWSLTR.BBS). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-21 Date Manipulation Commands (@J and @Y) @J and @Y Commands PURPOSE: Converts dates to and from string format (MM/DD/YYYY or DD.MM.YYYY) to numeric format NNNNNNNN FORMAT: @Jx or @Yx where 'x' references a @Zx variable. @Jx - Converts a date (MM/DD/YYYY or DD.MM.YYYY) stored in variable @Zx to a numeric string representing the number of days from 01/01/1900 (01.01.1900). For Example, if the date in @Z5 contains "06/01/1989", then issuing @J5 would overwrite the equivalent number of days between 01/01/1900 and 06/01/1989 in @Z5. Variable @Z5 can then be assigned to a numeric variable (@Nx) for further manipulation. The date string in @Zx prior to calling the @Jx function can be stored in either US or European format and can be in the short form (ie: 1/6 or 6.1 or 1/6/2). Note that if the date string is in error, the function will overwrite the @Zx variable with the numeric string "0" (without the quotes). The following example of using the @Jx variable demonstrates how it could be put to use on a subscription BBS which relies on the MEMODATE2 field: @z1=o17; @c3 Get Today's date @c4 @z2=u23; @c3 Get User's MEMODATE2 @c4 @j1 @j2 @n1=z1; @n2=z2; @n0=(n2-n1); Your subscription expires in @n0; days! @Yx - The opposite of @Jx. Converts a numeric string stored in variable @Zx, overwriting the @Zx variable with the date in MM/DD/YYYY or DD.MM.YYYY format depending on the users dateformat setting. Note that if the value in the @Zx variable is in error (ie: a negative number), the @Zx string will be overwritten with 01/01/1900 (or 01.01.1900 depending on the user's dateformat setting). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-22 Customizing MAGNUM - Display Files/MILC Commands Call Command (@K) @K Command PURPOSE: Calls a routine located at label @Px. Returns to area following the call upon a return (@#) instruction. FORMAT: @K(exp); @K(exp); - Same as @B(exp); but Kalls (calls) the part of the file identified by a @Px label. The result is identical to the @B(exp) command, but the return address is saved on an internal stack. To return back to the position after the @K(exp); is issued, issue the new MILC command @# to signify a return command. Example: @B1; unconditional branch to @P1 . . @P5 Label (signifies branch address) . . . @# Branch back to caller if called . by a @K(exp) command. . @P1 . . @K5; Branch (Kall) code at @P5 . Return to next instruction (here) . when done Kalls (calls) can be nested up to 50 levels. The MILC command @# ends the call, and returns processing back to the place in the file immediately preceeding the @K(exp); command. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-23 Security Level Commands (@L) @L Command PURPOSE: Processes all following text and commands for a specific security level only. FORMAT: @Lx where 'x' is a security level The @Lx command allows text/commands to be displayed/processed only if the remote user viewing the file has a security level equal to 'x'. The command @L10 for example, activates this feature such that the file display functions will only display text and process commands if the current user has a security level of 10. For Users at higher or lower levels, the command will act identically to the @C3 command. This will continue until another @Lx command is issued, which changes the security level again. To revert back to normal processing, the command @L0 will negate the @Lx command. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-24 Customizing MAGNUM - Display Files/MILC Commands Match Filename in FILE DATAbase (@M) command @M Command PURPOSE: Matches a Filename in the FILE DATAbase in preparation for external protocol(s). FORMAT: @Mx where 'x' references a @Zx variable. @Mx - Match filename in the FILE database. In preparation for external protocols, if a filename is in variable @Zx, the @Mx command will return the complete filespec (drive,path,filename,ext) in @Zx. For example, if the filename MAGNUM2.ZIP is in variable @Z5, then @M5 would overwrite @Z5 with D:\MAGNUM\GILMORE\MAGNUM2.ZIP or whatever the matching filespec would be for the file. If the filename is not found, or the filename is in a file area inaccessible to the user, then @Z5 will be null upon return from the @M5 function. If the filename is password protected, the user will be prompted for the password - if the password is wrong, the @Z5 variable will become null. If the value of x for @Mx is >= 40, then the following format is returned in variable @Zx: d:\path\filename[.ext] nnnnnn mm/dd/yyyy | | |_______ file date | |________________ file size |________________________________ filespec otherwise, if the value of x for @Mx is < 40, then the following format is returned in variable @Zx: d:\path\filename[.ext] MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-25 Numeric (@N) Commands (ie: mathematics, I/O, etc) @N Command PURPOSE: Numeric variable command. Performs arithmetic functions, screen I/O, and file writes. FORMATs: @Nx; Prints contents of @Nx @Nx=Ny; Assigns contents of @Ny to @Nx @Nx=y; Assigns a value to @Nx (ie: @N1=12;) @Nx(a,b); Assigns remote user's input to @Nx @Nx=Zy; Converts string variable @Zy to numeric, assign to @Nx @Nx=(EXP); Performs a mathematical expression @Nx("string"); Writes "string" to disk, followed by contents of @Nx where 'x' is the variable identifier (0 to 99), 'a' and 'b' are numbers, EXP is an arithmetic expression, "string" is a character string, 'y' is a number. The @Nx command is a very powerful command in that it performs many different tasks. It is capable of user input, screen or file output, performing arithmetic expressions, conversion of @Zx (string) variables to numeric, etc. There are 100 different numeric variables available (identified as @N0 to @N99). Each one of these is unique, and is capable of doing 32-bit arithmetic (long integers). This means that values can range from minus 2 billion something to plus 2 billion something. That's a fairly wide range. Note that floating point is NOT supported since it would take up too much program space and require too much processing time. You can, however make it appear as though floating point is supported by using a technique called scaling. It is beyond the scope of this document to cover scaling techniques, but if you are familiar with scaling you should have no problems. Note that all @N commands must end with the ';' (semicolon) character! Let's go through the different capabilities: DISPLAY THE CONTENTS OF A NUMERIC VARIABLE: This is the simplest form of the @N commands. Simply "@Nx;" (without quotes) where 'x' is the numeric variable (0 to 99) that you wish the contents displayed. If @N5 had the value 2005 in it, then the command @N5; embedded anywhere within the file will display "2005" (without quotes) on the remote user's screen. ASSIGNMENT TO A NUMERIC VARIABLE: This is the next simplest form of the @N command. Let's suppose that MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-26 Customizing MAGNUM - Display Files/MILC Commands Numeric (@N) Commands (ie: mathematics, I/O, etc) the numeric variable @N4 had the value 250: @N1=N4; @N2=12; In the above two examples, the contents of @N4 (which we said was 250) is assigned to @N1, therefore @N1 and @N4 now both hold the value 250. In the @N2 assignment, the value 12 is being assigned to @N2. GETTING REMOTE USER's NUMERIC INPUT: The @N command can also ask the remote user to input a number. The format of this form of the @N command is: @Nx(a,b); where 'x' (as usual) represents which N variable you want (0 to 99), and 'a' and 'b' represent the allowable range of numbers the user can enter. For example: Please Enter Your Age => @N1(5,120); This would print "Please Enter Your Age => " and wait for the user to enter a numeric response. Once the user enters their response, it is checked to see if it falls within the range of 5 to 120 (inclusive) and if it does, it assigns their answer to variable @N1. If it does not fall within the accepted range, a beep is emitted on the remote user's terminal and they are required to re-enter their answer. The display of the file will not continue until the remote user has entered an acceptable number. CONVERTING A STRING VARIABLE (@Zx) TO NUMERIC: The @Nx command is capable of converting a string variable to numeric, provided that the string variable consists of digits. If it does not consist of digits, the value 0 will be assigned to the numeric variable. Note that a numeric string of "0" and "John" will both result in the @Nx variable being assigned the value of 0. Some examples follow: @Z5="365"; @N2=Z5; @N2; In the above example, the string variable @Z5 is assigned the string "365". The next statement - @N2=Z5; - converts the string "365" to numeric and assigns the result in @N2. The next statement displays the value of @N2 which is 365. PERFORMING MATHEMATICS: And now for the real power of the @Nx command - mathematics! An example follows: @N5=365; @N4=(N5/7); There are @N4; weeks in a year. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-27 Numeric (@N) Commands (ie: mathematics, I/O, etc) In the above example, @N5 is assigned the value 365. Next, @N4 is assigned the result of the expression (N5/7) which is identical to 365/7, yielding a result of 52. Then "There are 52 weeks in a year." is displayed. As mentioned earlier, floating point is not supported. Therefore, the result of 365/7 is 52 (not 52.14286) - the decimal portion is simply truncated (dropped) - not rounded. The format @Nx=(EXP); for the (EXP) part must follow 3 rules: The expression must be enclosed in parenthesis. The first parameter MUST be a @N variable. The second parameter can be either a @N variable or number. In other words, @N5=(N10+12); is correct. @N5=(N10+N30); is correct. @N5=(45+N3); is incorrect. @N5=(45+70); is incorrect. As always, note the lack of any spaces, and the terminating ';'. The operation to be performed in the EXP part of the example can be one of: + addition - subtraction * multiplication / division % modulus (remainder) ^ XOR (bitwise exlusive or) | OR (bitwise OR) & AND (bitwise AND) Most of you will be using the first 4 operations. The next 4 (%,^,|,&) are beyond the scope of this document, therefore - if you are not familiar with what a modulus, XOR, OR, or AND are then you will have no need for them anyway. WRITING THE @Nx VARIABLE TO DISK: With all the power of the @Nx command, it would certainly be a shame if there were no way to write the contents of some of the variables to disk. This is handy with such files as Questionairres. To write the contents of a @Nx variable to disk, simply: @N5("Total Price: $"); Assuming @N5 had the value 500. The above statement would write the following line to a disk file: Total Price: $500 Another example might be: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-28 Customizing MAGNUM - Display Files/MILC Commands Numeric (@N) Commands (ie: mathematics, I/O, etc) @Z1=O10; @N1=Z1; @N2=72; @N1(N2-N1); @N1("Years left for average life expectancy: "); Assuming the user's age is 25, we place the user's age (see @O command) in the variable @Z1. Next, we assign the numeric equivalent to numeric variable @N1. Numeric variable @N2 is assigned the value 72. We then assign to @N1 the result of the expression (N2-N1) or 72-25. The following line then gets printed to disk: Years left for average life expectancy: 47 Which file does it write to? Whatever file is currently being displayed, the output file will have the same name but with an extension of ".R??", where the "??" will be replaced with the com port number the user is logged on to. The output file will always be placed in the SYSOUT directory. So if the user was displaying "c:\gs\com\1\bul_dir\ques1" or "c:\gs\com\1\bul_dir\ques1.bbs" or "c:\gs\com\1\bul_dir\ques1.scr" the output file will be "ques1.r01" if the user is on com port 1, "ques1.r02" if the user is on com port 2, etc the output file will always be placed in the SYSOUT DIRECTORY. The 'R' in ".R01", ".R02", etc stands for "Response" since we are normally writing the user's responses to the output file. We used the above example file names since they are all the same - the extension simply gets stripped off, and replaced with the ".R??" extension (as explained above), while the path is changed to point to the session directory. It's that simple! Note that if the response file does not exist, it will be created. If the response file already exists, it will be appended to. How do we know which user was online at the time we wrote the answers to the disk file? When the very first response gets written to the response file, the system will write the user's name, id number, date, time and some other info to the file before writing the response to the file. AN EXAMPLE QUESTIONAIRRE FILE: Questionairre #2 - Fictitious credit card order @P1 1) Credit Card # => @Z0(20); @P2 2) Purchase of: A) 20 Mb Hard Disk ($100) B) 2400 baud modem ($ 95) C) Personal Computer ($900) D) MBBS for OS/2 ($400) Choice (A, B, C or D) => @Z1('ABCD'); @b40(Z1="A"); @b41(Z1="B"); @b42(Z1="C"); @b43(Z1="D"); MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-29 Numeric (@N) Commands (ie: mathematics, I/O, etc) @P3 Your order for $@n1;.00 + $10.00 for shipping/handling comes to a grand total of @n2=(n1+10);$@n2;.00 Is all of the above information correct (Y/N) => @Z2('yn'); @B1(Z2="N"); @Z0("Credit Card # "); @Z3("Purchased: "); @N2("Total Price: $"); @b49(0=0); @p40 @n1=100; @Z3="20 Mb Hard Disk"; @b3(0=0); @p41 @n1=95; @Z3="2400 baud modem"; @b3(0=0); @p42 @n1=900; @Z3="Personal Computer"; @b3(0=0); @p43 @n1=400; @Z3="MBBS for OS/2"; @b3(0=0); @p49 Thank you for your order, @u3 We'll be sending that off to: @u3 @u4 @u2 @u6 @u7 @u8, @u9, @u10 @u11 @c9 Assuming "ques2.bbs" is the questionnaire, and the user on node 1 completed it, the response file "ques2.r01" will be logged in the SYSOUT directory. A typical might look like the following: ------------------------------------------------------------ **** USER: JOE S USER ****** ID: "/3" AGE: 36 **** FROM: self 123 Sesame St. Los Angeles, CA 90067 - USA ** PHONE1: 213-555-2125 PHONE2: 213-555-1900 ext 25 * * * ANSWERS LOGGED AT 18:43 on Thursday, 13 April 1989 Credit Card # 1234-123-123-123 Purchased: MBBS for OS/2 Total Price: $410 ------------------------------------------------------------ **** USER: JOHN K DOE ****** ID: "/248" AGE: 22 **** FROM: Unlimited Products, Inc. 24 Tower Drive, Suite 135 Chicago, IL 60601 - USA ** PHONE1: (312) 555-4321 PHONE2: (312) 555-1234 * * * ANSWERS LOGGED AT 20:02 on Thursday, 13 April 1989 Credit Card # 1234-5678-9012-3456 Purchased: 2400 baud modem Total Price: $105 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-30 Customizing MAGNUM - Display Files/MILC Commands Other (Miscellaneous) Commands (@O) @O Command PURPOSE: 'OTHER' (miscellaneous) information will display about the system date and time, and other miscellaneous information. FORMAT: @Ox where 'x' is the parameter (a number) representing what to display. The command @Ox in a display file will be replaced with information about the system date, time or other miscellaneous information depending on the value of the 'x' parameter. The 'x' parameter can range from 0 to 26 as follows: @O0 - Hours (ranges from 00 to 23) @O1 - Minutes (ranges from 00 to 59) @O2 - Seconds (ranges from 00 to 59) @O3 - Hundredths of seconds (ranges from 00 to 99) @O4 - Day of month (ranges from 00 to 31) @O5 - Month (ranges from 01 to 12) @O6 - Year (the current 4-digit year) @O7 - Day of week (string: "Sunday", "Monday", etc) @O8 - Month (string: "January", "February", etc) @O9 - Time (string: "3:57 PM", "12:01 AM", etc) @O10 - User's age @O11 - Minutes user has been online this call @O12 - NODE # user is on @O13 - Total calls received on PORT # @O14 - Previous caller's name (up to 62 chars) @O15 - Previous caller's location (up to 62 chars) @O16 - Magnum Version Number (up to 9 chars) @O17 - Current date in either MM/DD/YYYY or DD.MM.YYYY format depending on the user's dateformat setting. @O18 - Used for creating a random 8-digit string. This is MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-31 Other (Miscellaneous) Commands (@O) related to RJE programs, such that if someone starts the same RJE program more than once, you don't want it writing its output to the same filename every time. This command provides a unique way of creating a filename which is unique (less the extension) to pass to RJE or other programs external to Magnum requiring an output filename to write to. Example: @z0="pgmname.exe"; @z1=o18; @z1=(z1+".txt"); @e1 The string returned is time-dependent. It consists of: HHMMSShh where: HH = current hour of current day MM = current minute of current day SS = current seconds of current day hh = current hundredths of seconds of current day @z1=o18; is identical to doing the following: @z1=z0; @z2=o1; @z1=(z1+z2); @z2=o2; @z1=(z1+z2); @z2=o3; @z1=(z1+z2); @O19 - Logon type: L = Local Logon (keyboard/console or local logon module) R = Remote Logon (modem) PF = Pipe in Full Duplex (OS/2 workstation) PH = Pipe in Half Duplex (DOS workstation) Half duplex pipes have the following restrictions: - Cannot stop displays with <Ctrl-X> or <SpaceBar> - Cannot run interactive child (door) programs unless those programs conform to Magnum's duplex-switching scheme (contact Gilmore Systems for more information). - Chat mode not allowed. @O20 - The 10-digit Serial Number of Magnum for THIS machine. @O21 - The 10-digit Parent Serial Number of Magnum. @O22 - "TRUE" or "FALSE" (without the quotes) if the system has the 'Extended FileBase' option. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-32 Customizing MAGNUM - Display Files/MILC Commands Other (Miscellaneous) Commands (@O) @O23 - "TRUE" or "FALSE" (without the quotes) if the system has the 'Extended MsgBase' option. @O24 - Returns the DEVICENAME used for this node. @O25 - returns OS version (ie: "1.30", "2.00", "2.10", etc). @O26 - displays ID number for 'outside mail id'. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-33 Position (Label) Commands (@P) @P Command PURPOSE: Defines a POSITION (LABEL) in a file to be a target for a BRANCH command. FORMAT: @Px where 'x' is the label number. The POSITION (or LABEL) command simply marks a place in the display file for later use as a target for a BRANCH instruction. 'x' can range from 0 to 99. See the @B command for examples. NOTE: 'x' must fall within the range of 0 to 99. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-34 Customizing MAGNUM - Display Files/MILC Commands Retain (@R), File (@F) and Query (@Q) MILC Variables @Z & @N @R Command PURPOSE: To retain the values of all @Zx and @Nx MILC variables such that they can be used by other files. (IE: MAKES @Zx and @Nx variables GLOBAL). @FORMAT: @Rx where 'x' is one of 0 or 1 as follows: @R1 - retain contents of @Zx and @Nx variables after file display. @R0 - do not retain contents of @Zx and @Nx variables (default). Whenever the display routines come across the @R1 command within a display file, the @Nx and @Zx variables will be retained. This means that any subsequent display file can use the previously stored values stored within these variables. Note that the use of @R1 makes these variables global, so if one display routine changes the contents of any given variable, all subsequent display routines will find the value to be that of the most recent assignment statement to the variable(s). Note that the @Ix command ("include") will remain unaffected by the @R1 command. To negate the @R1 command, simply issue a @R0 command and the file display routines will return to the normal way in which Magnum used to process its MILC commands. When the display file routine starts, it initializes all @Zx variables and to nul (""), and all @Nx variables to zeros (0). The @R1 command merely tells the file display routine not to do this for all subsequent file displays. The @R0 command negates this, causing the file display routines to reinitialize all @Zx and @Nx variables. CAUTION: User messages (in the message section) will result in the @Nx and @Zx variables not being initialized (ie: they will have access to the values stored in these variables). Note that users having access to MILC commands within messages will overwrite these values!! It would be a wise precaution to issue a @R0 command prior to entering the message menu. NOTE that any text display you've created the old way which depends on @Nx and @Zx variables being initialized to zeros and nulls should be modified such that they perform their own initialization (this could easily be accomplished by including an initialization file with the @I4 command. Because of the problems which might occur with the globality aspect of using the @R1 command above, another solution (and much greater power as a result) is to have the contents of the @Zx and @Nx variables saved in a unique file. This can be accomplished with two new MILC variables: @Fx - where 'x' is a unique file identifier which can range from 0 to 99. When an @Fx command is invoked, the contents of the @Zx and @Nx variables are saved to a unique filename which you will know as 'x'. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-35 Retain (@R), File (@F) and Query (@Q) MILC Variables @Z & @N @Qx - where 'x' is a unique file identifier which can range from 0 to 99. When an @Qx command is invoked, the contents of the @Zx and @Nx variables are restored from the unique filename which the @Fx command saved them to. When using @Fx to save your variables and @Qx to restore them, you don't have to use the @R1 command. However, the @Fx and @Qx functions have advantages and disadvantages over using the @R1 function. For example, with @Fx and @Qx, any subsequent display file must know which 'x' file to restore from. On the other hand, the @R1 function makes the variables global across the board which would proably not be a good idea when doing messages. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-36 Customizing MAGNUM - Display Files/MILC Commands Stack Keystrokes Command (@S) @S Command PURPOSE: Places Keystrokes in the user's command stack, as if the user typed in the characters him/herself. FORMAT: @Sx where 'x' refers to which @Zx variable to stack from. This command places characters in the user's command stack. The 'x' tells which @Zx variable to place the commands in the stack from. For example, if reading a display file from the main menu, you could place the user in the [F]iles menu looking at all new files since their last logon with the following: @Z7="\\f\n\+\\"; @S7 @C16 Note that because the semicolon (;) character is the terminataion character of a string assignment, that character cannot be used within the string itself! The @Sx command, while copying the contents of the @Zx variable containing the string to place in the command stack, converts all backslash (\) characters to semicolons. In the above example, the @S7 command would place the following in the user's command stack: ;;f;n;+;; Note that this only PLACES commands in the user's command stack. Upon ending (or terminating with @C16) the display, all system input (prompts) will get their input from the keystrokes now stored in the user's command stack until the last keystroke stored is read. Magnum will revert back to getting its input from the user (modem) when no more keystrokes remain in the command stack. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-37 Text to Log (activity) File (@T) @T Command PURPOSE: Sends text within a quoted string or a @Zx variable to the ACTIVITY.x file. FORMAT: @Tx @T"string" This command writes to the ACTIVITY.x file. There are two ways to send text to the ACTIVITY.x file: The following example writes the text appearing within the double-quotes to the ACTIVITY file: @T"This is a sample text line" The following example writes the contents of variable @Z5 to the ACTIVITY file: @T5 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-38 Customizing MAGNUM - Display Files/MILC Commands User Substitution Commands (@U) @U Command PURPOSE: 'USER' information will display. Ideally suited for giving the illusion of a customized display file to the user. FORMAT: @Ux where 'x' is the parameter (a number) representing what to display. The command @Ux in a display file will be replaced with information about the user depending on the value of the 'x' paramter. The 'x' parameter can range from 0 to 80 as follows: @U0 - Deleted or active user. Displays "deleted" or "active". @U1 - Displays User's ID number. Up to 10 chars. @U2 - Displays user's LAST name. Up to 20 chars. @U3 - Displays user's FIRST name. Up to 20 chars(See @U77,@U78,@U79) @U4 - Displays user's MIDDLE name. Up to 10 chars. @U5 - Display's "Private Messages" or "No Private Messages" @U6 - Displays user's STREET1 (or company/handle) - up to 40 chars. @U7 - Displays user's STREET2 (or street address) - up to 40 chars. @U8 - Displays user's CITY - up to 20 chars. @U9 - Displays user's STATE or PROVINCE - up to 20 chars. @U10 - Displays user's ZIP or other postal info - up to 20 chars. @U11 - Displays user's COUNTRY - up to 20 chars. @U12 - Displays user's PASSWORD - up to 20 chars (be carefull!) @U13 - Displays date of user's FIRST CALL (10 chars) @U14 - Displays date of user's LAST CALL (10 chars) @U15 - Displays time of user's LAST CALL (5 chars) @U16 - Displays user's DATE OF BIRTH (10 chars) @U17 - Displays user's PHONE #1 (up to 20 chars) @U18 - Displays user's PHONE #2 (up to 20 chars) @U19 - Displays user's LAST "NEW FILES" search date (10 chars) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-39 User Substitution Commands (@U) @U20 - Displays user's CPU TYPE (15 chars) @U21 - Displays user's CONFERENCE letters (up to 26 chars) @U22 - Displays user's MEMODATE #1 (10 chars) @U23 - Displays user's MEMODATE #2 (10 chars) @U24 - Displays sysop's COMMENT about user (up to 60 chars) be careful with this one! @U25 - Displays user's selected FILE XFER PROTOCOL (up to 10 chars) @U26 - Displays user's PERIOD TYPE (up to 5 chars) @U27 - Displays "Expert" or "Novice" menu types. @U28 - Displays "Authorized" or "Unauthorized" (is user locked out?) @U29 - Displays user's color settings ("color" or "B/W") @U30 - Displays user's setting of "'More' prompt" or "No 'More' prompt" @U31 - Displays "Erase 'More' prompt" or "Do not erase 'More' prompt" @U32 - Displays "Single-keystroke commands" or "C/R" @U33 - Displays "Message Deletion" or "No Message Deletion" @U34 - Displays user's LINES PER SCREEN (up to 3 chars) @U35 - Displays user's SECURITY LEVEL (up to 5 chars) @U36 - Displays user's # OF FILES UPLOADED (up to 5 chars) @U37 - Displays user's # OF FILES DOWNLOADED (up to 5 chars) @U38 - Displays user's ADJUSTED CHARS/SEC XFER RATE (up to 5 chars) @U39 - Displays user's UL/DL RATIO (up to 10 chars - ie: "10 to 1") @U40 - Displays user's TOTAL CALLS (up to 10 chars) @U41 - Displays user's MINUTES REMAINING FOR THIS CALL (up to 10 chars) @U42 - Displays user's MINUTES REMAINING FOR THE PERIOD (up to 10 chars) @U43 - Displays user's LAST MSG NUMBER READ. Format of display is: base:refnum (ie: 3:A213CEA009A2 indicating MsgBase 3, MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-40 Customizing MAGNUM - Display Files/MILC Commands User Substitution Commands (@U) Ref# A213CEA009A2). @U44 - Displays user's ACCUMLATED UPLOAD K BYTES (up to 10 chars) @U45 - Displays user's ACCUMLATED DOWNLOAD K BYTES (up to 10 chars) @U46 - Displays user's ALLOWED NUMBER OF D/L's FOR PERIOD (up to 10 chars) @U47 - Displays user's ALLOWED DOWNLOAD K BYTES FOR PERIOD (up to 10 chars) @U48 - Displays user's BAUDRATE (up to 5 chars) @U49 - Displays "Modem Error Correction" or "No Modem Error Correction" @U50 - Displays allowable "@" commands for messages (up to 26 chars) @U51 - Displays User Date Format ("U.S." or "EUROPE") @U52 - Displays a string of up to 26 chars showing the user's FREE download areas) @U53 - Displays the number of FREE downloads a user has performed @U54 - In preparation for running certain externals created by Gilmore Systems, this MILC command supplies the complete filespec (drive,path,filename) for the MBBSINIT.x file associated with the node the user is on. @U55 - Like @U54 above, but supplies filespec for STARTUP.x instead. This is in preparation for running externals created from 3rd party software developers. @U56 - User's MSG_R_AREAS (up to 26 chars) @U57 - User's MSG_W_AREAS (up to 26 chars) @U58 - User's MSG_L_AREAS (up to 26 chars) @U59 - User's FILE_U_AREAS (up to 26 chars) @U60 - User's FILE_D_AREAS (up to 26 chars) @U61 - User's FILE_L_AREAS (up to 26 chars) @U62 - Displays a string of up to 78 characters showing the user's areas of personal interests. @U63 - User's compression default type "ARC" or "ZIP" (w/o quotes). @U64 - Number of PUBLIC messages entered by user. @U65 - Number of PRIVATE messages entered by user. @U66 - Number of RJE Jobs run by user. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-41 User Substitution Commands (@U) @U67 - The complete filespec (drive,path,filename) of the last message saved by the user. Note that the REF# of last message saved for any external programs you may have written can be derived from the filespec of the message. For example: Filespec: D:\MAGNUM\MSG_DIR\K\K1234567.890 Ref#: K1234567890 Note that a CC (Carbon Copy) is not considered to be a message saved. In the case of saving a message with CC's, only the original message will be deemed to be the 'last message saved'. @U68 - the complete filespec (drive, path, filename) of the last file the user uploaded during THIS session. This variable is ideally used to pass this information to an external program right after the user performs a file upload. This can be accomplished with the POSTUP.BBS display file. @U69 - the current MessageBase the user is in. @U70 - the current FileBase the user is in. @U71 - Returns Y or N depending on whether the user's ID is reusable. @U72 - Returns user account type (U or M). U=user, M=mail. @U73 - Returns Y or N depending on if the user can use Remote Mail. @U74 - Returns the MSG GROUP assigned to this user (0-255). @U75 - Returns the FILE GROUP assigned to this user (0-255). @U76 - displays Y or N if the user is using a handle. @U77 - displays user's handle (if using a handle). @U78 - if user is using a handle, displays handle, else first name. @U79 - if user is using a handle, displays handle, else FULL name. @U80 - displays Y or N if the user has access to outside mail. @U81 - The user's internet id name (e-mail address). This does NOT include the domain name (ie: john). @U82 - The user's complete internet id name (e-mail address) including the domain name (ie: john@mybbs.com). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-42 Customizing MAGNUM - Display Files/MILC Commands View System Variables (@V) @V Command PURPOSE: Allows static information about the system/session to be viewed and/or passed to external programs. FROMAT: @Vx (where 'x' is the one of the system variables described below. These variables are generally viewed or assigned to a @Zx variable). System related information can be used to pass as information to external programs. These variables are not changeable (most are changeable by "re-compiling" your STARTUP files), which is why we call it the VIEW command rather than something else). The @Vx command can be used much like the @Ux and @Ox command in that it can be assigned to a @Zx variable. The @Vx commands are as follows (where 'x' is the static variable you wish to use): 0 = Comport handle (ie: to pass to an external program such as an external file xfer program). NOTE: The comport handle is NOT automatically passed to child processes. To pass the handle, you will need to do two things: - Make the child process aware of the handle number by including the contents of @V0 on the command line: @z1=v0; - The comport handle is automatically marked UN-INHERITABLE to child processes. The 128 bit of MILC variable @N0 is used to tell Magnum that the comport handle is to be inherited by your external child process. Simply OR the value 128 into the @N0 variable: @n0=7; @n0=(n0|128); See the description of CHILDREN.BBS in the "Creating Subdirectories" portion of the manual. 1-26 = The actual DIRECTORIES of file areas A thru Z, such that 1=file directory A, 2=file directory B,...26=file directory Z. 27-52 = The actual file DESCRIPTION strings for file areas A thru Z such that 27=file description A, ... 52=file description Z. 53-78 = The actual message DESCRTIPTION strings for message conference areas A thru Z such that 53=message description A, ... 78=message description Z. 79 = The PROGRAM directory. 80 = The SESSION directory. 81 = The BULLETIN directory. 82 = The MENU directory. 83 = The HELP directory. 84 = The DISPLAY directory. 85 = The EXTERNAL directory. 86 = The RJE directory (where RJE programs and menu(s) are). 87 = The MESSAGE directory (parent directory only, there are 26 subdirectories (A-Z) under this). 88 = The WORK directory. 89 = The USERS directory. 90 = The SYSOUT directory. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-43 View System Variables (@V) 91 = The RJE RESULTS directory (it's one of your FILE directories). 92 = ACTIVITY.x handle (ie: to pass to an external program such as an external file xfer program). NOTE: The ACTIVITY.x handle is NOT automatically passed to child processes. To pass the handle, you will need to do two things: - Make the child process aware of the handle number by including the contents of @V92 on the command line: @z1=v92; - The ACTIVITY.x handle is automatically marked UN-INHERITABLE to child processes. The 64 bit of MILC variable @N0 is used to tell Magnum that the ACTIVITY.x handle is to be inherited by your external child process. Simply OR the value 64 into the @N0 variable: @n0=7; @n0=(n0|64); See the description of CHILDREN.BBS in the "Creating Subdirectories" portion of the manual. - NOTE: The child process inheriting this handle may use it for WRITE-ONLY (the handle is not available for reading). 93 = The PID (process identification number) of MSESSION.EXE for this session. The PID will be non-zero if this call is successful. 94 = This variable holds the name of the current program (no path information, and no extension). This will normally be MSESSION, however, if you're using an alternate language, the name might be something like MSES_GER or MSES_FRE, etc. This will allow you to query (via MILC commands) what language you're using. 95 = Returns BBSID (for use with QWK). Generally the last 8 digits of the serial# unless overriden (in the STARTUP file for that node) by the QWK_BBSID keyword and parm. 96 - The system's internet domain name (ie: mybbs.com). 97 - The system's [internet] timezone (ie: PST, PDT, EST, EDT, etc) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-44 Customizing MAGNUM - Display Files/MILC Commands Wait Command (@W) @W Command PURPOSE: Waits a specified number of miliseconds, then continues. FORMAT: @Wx where 'x' is the number of miliseconds to wait. The WAIT (or pause) command, waits 'x' number of miliseconds, then continues. This command is useful in your GOODBYE.BBS file to create a pause while the modem empties its buffer to the user prior to disconnecting. For example, @W2000 will cause a delay of 2 seconds before proceeding - this is usually sufficient to empty the modem's buffer before ending the GOODBYE.BBS file. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-45 String (@Z) Commands (ie: String Logic, I/O, etc) @Z Command PURPOSE: String variable command. Performs string functions, screen I/O, and file writes. FORMATs: @Zx; Prints contents of @Zx @Zx=Zy; Assigns contents of @Zy to @Zx @Zx="string"; Assigns a string to @Zx (ie: @Z1="John";) @Zx('abc'); Get's remote user's input - restricts input to 'abc' @Zx(y); Get's remote user's input - up to 'y' chars. @Zx=Ny; Converts numeric variable @Ny to string, assign to @Zx @Zx=Oy; Assigns contents of @Oy to @Zx (See @O) @Zx=Uy; Assigns contents of @Uy to @Zx (See @U) @Zx=Vy; Assigns contents of @Vy to @Zx (See @V) @Zx(EXP); Performs a string expression (concatenation) @Zx("string"); Writes "string" to disk, followed by contents of @Zx where 'x' is the variable identifier (0 to 99), 'abc' are characters, EXP is a string expression, "string" is a character string, 'y' is a number. The @Zx command is a very powerful command in that it performs many different tasks. It is capable of user input, screen or file output, performing string concatenations, conversion of @Nx (numeric) variables to string, etc. There are 100 different string variables available (identified as @Z0 to @Z99). Each one of these is unique, and is capable of storing strings of up to 112 characters each. Note that all @Z commands must end with the ';' (semicolon) character! Let's go through the different capabilities: DISPLAY THE CONTENTS OF A STRING VARIABLE: This is the simplest form of the @Z commands. Simply "@Zx;" (without quotes) where 'x' is the string variable (0 to 99) that you wish the contents displayed. If @Z5 had the string "John" in it, then the command @Z5; embedded anywhere within the file will display "John" (without quotes) on the remote user's screen. ASSIGNMENT TO A STRING VARIABLE: This is the next simplest form of the @Z command. Let's suppose that the numeric variable @Z4 had the value "Good Morning": MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-46 Customizing MAGNUM - Display Files/MILC Commands String (@Z) Commands (ie: String Logic, I/O, etc) @Z1=Z4; @Z2="John"; In the above two examples, the contents of @Z4 (which we said was "Good Morning") is assigned to @Z1, therefore @Z1 and @Z4 now both contain the string "Good Morning". In the @Z2 assignment, the string "John" is being assigned to @Z2. GETTING REMOTE USER's STRING INPUT: The @Z command can ask the remote user to input a string or a single character. By way of example, let's demonstrate the two forms of string or single-character input: @Z5(20); Accepts up to a 20-character string, assigns to @Z5 @Z6('YN'); Accepts either the 'Y' or the 'N' character - nothing else. Assigns the string "Y" or "N" to @Z6. As a working example, let's ask the user for their favorite sport: What is your favorite sport => @Z1(20); This would print "What is your favorite sport => " and wait for the user to enter a response of up to 20 characters. When the user presses his ENTER (or C/R) key, whatever they typed will be assigned to string variable @Z1. Note that responses are always required! Many times, you'll be offering the user a choice (Y/N) or a menu selection that requires a single-character response. For example: Are you sure (Y/N) => @Z1('yn'); would print "Are you sure (Y/N) => " on the user's screen, then wait for the user to respond with 'y' or 'n' before continuing. Note that upper/lowercase is not important - 'y' is the same as 'Y' as far as the system is concerned. Also note that if the user's environment settings is set for single-character responses, the system will not wait for them to press ENTER (or C/R) before continuing, otherwise their single-character response will not be processed until they press ENTER (or C/R). In the above example, the user's response will be stored as a single-character string in variable @Z1. Note that we will use double quotes (" ") to denote strings, and single quotes (' ') to denote single characters. In a menu or multiple choice type of situation, the following might be found: A) True B) False C) Could go either way D) I don't know MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-47 String (@Z) Commands (ie: String Logic, I/O, etc) Enter your choice => @Z2('abcd'); You are not limited by alphabetic characters either, the above could be represented with single-digit numbers as well: 1) True 2) False 3) Could go either way 4) I don't know Enter your choice => @Z2('1234'); Or it could contain a mixture: A) Some of the time 1) Skip this question B) Most of the time 2) Quit, return to system C) None of the time D) All of the time Enter your choice => @Z2('abcd12'); CONVERTING A NUMERIC VARIABLE (@Nx) TO STRING: The @Zx command is capable of converting a numeric variable to string. Suppose that @N2 had the numeric value of 365: @Z5=N2; In the above example, the numeric variable @N2 has a value of 365. This is converted to the string "365" and assigned to string variable @Z5. GETTING MISCELLANEOUS SYSTEM OR USER INFORMATION: The @Zx command can also be assigned any of the @Ox, @Ux or @Vx strings. See @O, @U, @V commands for their parameters. For example: @Z1=O10; assigns the user's age (as a string) to string variable @Z1 Remember that the @Nx (numeric) variables cannot obtain any @O or @U values. @Nx values can only obtain those values from @Zx variables: @Z1=O10; @N1=Z1; This assigns the user's age to string variable @Z1, then converts the numeric string in @Z1 to numeric for assignment to @N1. PERFORMING STRING CONCATENATION: String concatenation is simply taking two strings, and combining them MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-48 Customizing MAGNUM - Display Files/MILC Commands String (@Z) Commands (ie: String Logic, I/O, etc) into one - as long as the resultant string is 112 characters or less. Examples: Suppose that @Z1 contained the string "Bed": @Z1=(Z1+" time"); would result in @Z1 containing "Bed time". or @Z1=(Z1+"time"); would reslut in @Z1 containing "Bedtime". Suppose that @Z1 contains "John", and @Z2 contains "is 25 years old": @Z3=(Z1+Z2); would result in "Johnis 25 years old" You might need 2 steps in that case: @Z3=(Z1+" "); @Z3=(Z3+Z2); would result in "John is 25 years old" WRITING THE @Zx VARIABLE TO DISK: With all the power of the @Zx command, it would certainly be a shame if there were no way to write the contents of some of the variables to disk. This is handy with such files as Questionairres. To write the contents of a @Zx variable to disk, simply: @Z5("Favorite Sport: "); Assuming @Z5 contained the string variable "swimming", the above command would write the following line to a disk file: Favorite Sport: swimming Basically, writing either a @Zx or @Nx variable to disk is the same. The format for @Zx variables are: @Zx("string"); The format for @Nx variables are: @Nx("string"); where 'x' is the number of the string or numeric variable you want written, and "string" is any descriptive string you want (as an aid in telling you what you've written). See the @N command "Writing the @Nx VARIABLE TO DISK" section for more examples and an explanation of what files actually get written to. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-49 Character Display - @\ command. @\ Command PURPOSE: Force display of a character. FORMAT: @\x Displays character equivalent of 'x'. The IBM character set contains 256 characters (values 0 to 255). Note that if you're using a 7 databit setup only characters 0 to 127 are available, however, 99% of all BBSs are running an 8 databit setup. Unfortunately, many of you are limited as to what characters can appear in your display files by the characters which are on your keyboard. For example, there's no BEL character on your keyboard (sends an audible beep to the remote user). This is where the @\x command comes in. The command: @\7 sends a BEL character to the screen (and comport). Other examples: @\13 CR (carriage return) @\10 LF (line feed) Valid values are @\0 through @\255 exluding the @\17 (XON) and @\19 (XOFF) equivalents. If @\x has a negative value, or a value of 17, 19, or greater than 255, then the statement is ignored. Note that the number used as 'x' in a @\x statement is terminated by the first non-digit. Therefore, if you wanted to a display a numeric character following a BEL (@\7) such as the number 10, then the statement @\710 will NOT work. One alternative around this might be the following: @N2=10; @\7@n2; or @N2=10; @\7@\[2] (See "Indirect Addressing" later in this chapter) Using the advanced features of Indirect Addressing (explained on the pages of this chapter entitled "Advanced MILC Command Usage - Indirect Addressing"), the following example demonstrates how to display the entire character set: @N5=0; @P0 @\[5+] @B0(N5<256); NOTE: The @\x command is available to ALL users, and is NOT part of the MILC_CMDS field of each user's record. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-50 Customizing MAGNUM - Display Files/MILC Commands "Sysop Only" MILC commands: @$x, @&x, @!x, and @?x Four MILC commands are designated "sysop use only". These are not part of the MILC_CMDS field of any user record including the sysop. The commands perform the following functions: @$x - Save @Zx and @Nx values to a file in MBBSEXEC format @&x - Restore @Zx and @Nx values from a file in MBBSEXEC format. @!x - Delete a file. @?x - Check for file existence. @$x - Save @Zx and @Nx values to a file in MBBSEXEC format This command will save the values of all of the @Zx and @Nx variables in a file compatible with MBBSEXEC format (see MBBSEXEC - Advanced section). The 'x' refers to which @Zx variable holds the filename to save to. Example: @Z5="milcvar.val"; @$5 @&x - Restore @Zx and @Nx values from a file in MBBSEXEC format This command will restore the values of all of the @Zx and @Nx variables from a file compatible with MBBSEXEC format (see MBBSEXEC - Advanced section). The 'x' refers to which @Zx variable holds the filename to restore from. Example: @Z5="milcvar.val"; @&5 @!x - Delete File This command will delete a file. The 'x' refers to which @Zx variable holds the filename to delete. Example: @Z5="milcvar.val"; @!5 @?x - Check for File Existence This command tests for the existence of a file. The filename ([d:][path]filename[.ext]) to test is in @Zx. The result is placed in @N0 (1=exists, 0=does not exist). Example: @Z5="d:\magnum\testfile.ext"; @?5 @b1(n0=1); The file does NOT exist! @c16 @p1 The file DOES exist! These four MILC commands (@$x, @&x, @!x, and @?x) can be used to pass the values of the @Zx and @Nx variables to MBBSEXEC with (see MBBSEXEC - Advanced Section). The @Nx variables in MSESSION correlate with the @TALLYx variables in MBBSEXEC. The @Zx variables in MSESSION correlate with the @STRINGx variables in MBBSEXEC. See the SAVE_DATA() and RESTORE_DATA() commands in the advanced section of MBBSEXEC. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-51 "Sysop Only" MILC commands: @$x, @&x, @!x, and @?x These four MILC commands (@$, @&x, @!x, and @?x) are available to the Sysop only. This means that any message in the message database wishing to utilize these commands must have the Sysop (ID: /0) as the originator of the message. All other display files may contain these commands since those files must have been created locally anyway (ie: external menus, help screens, HELLO?.*, SEC*.*, etc). These commands, as with all other MILC commands will have no effect if included in a file being viewed from the File section's "[A]ccess Arc/Zip file" function or "[R]ead Ascii File". MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-52 Customizing MAGNUM - Display Files/MILC Commands Advanced MILC Command Usage - Indirect Addressing Advanced MILC Command Usage - Indirect Addressing (Indexing) The MILC command language includes an advanced feature known among programmers as "indirect addressing" (or "indexing"). If you are a programmer, or if your company has programmers, this section might be best left to them. NOTE: Please have a thorough understanding of the MILC command language prior to using indirect addressing! Nearly every MILC command is of the format @Xn (where '@' is the MILC command character, 'X' is the command group, and 'n' is the command function or variable number). Indirect addressing eliminates the need to specify 'n' directly. By means of example, lets suppose you wanted to display the values of ALL of the @Ux variables, one per text line. Up until now, the only way to do this was as follows: 0 : @U0 1 : @U1 . . . 75 : @U75 The above would take 76 message lines (or 76 display file lines) to accomplish the task of displaying @Ux variable contents from @U0 through @U75. The following example demonstrates how to perform the same task with indirect addressing: @N5=0; @P0 @N5; : @U[N5] @N5=(N5+1); @B0(N5<76); Note that in the above statements, we've introduced brackets '[' and ']' after the @U variable. In the past, @U had to be followed by the number of which @U variable you wanted. With brackets, the contents of the brackets tell Magnum to get this number from the @N5 variable. The first time through the loop, @N5 contains 0 (zero), so @U[N5] would be identical to @U0. The second time through the loop, @N5 contains the value of 1, so @U[N5] would be identical to @U1, and so on. Note that there are two acceptible ways of indirect addressing. Assuming the value is in variable @N5 (indirect addressing ALWAYS references a @Nx variable), the following two statements are identical: @U[N5]; @U[5]; We chose to use the @U[N5] method above for your convenience. Our prefered method would be @U[5]. Keep in mind that the above examples used the @Ux variables with indirect addressing, however, idirect addressing can be used with any MILC variable that expects the command-group character to be followed by the variable number or command function. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-53 Advanced MILC Command Usage - Indirect Addressing EXCEPTIONS TO INDIRECT ADDRESSING: YOU CANNOT INDIRECTLY ADDRESS MILC VARIABLES WHICH: 1) Appear within parenthesis 2) Appear to the right of an = (assignment) sign. 3) The @Px MILC variable cannot be indirectly addressed 4) The @Ix@Zy statement: The @Zy portion cannot be indirectly addressed. The following demonstrates some correct and incorrect usage of indirect addressing: @U[12] CORRECT @B[17](0=0); CORRECT @N5=Z[3]; INCORRECT (brackets illegal on right of '=') @Z5=(Z[2]+Z4); INCORRECT (within parenthesis and right of '=') @\[14] CORRECT Indirect addressing comes in most handy when building jump tables. For example: 1 - Today's News 2 - Stock Quotes 3 - Online Shopper 0 - Quit, Return to BBS Choice (1,2,3,0) => @N5(0,3); @B[5]; @P1 - - - Today's News - - - . . . @C16 @P2 - - - Stock Quotes - - - . . . @C16 @P3 - - - Online Shopper - - - . . . @C16 @P0 @C16 The same rules of a terminating semicolon (;) still apply for those MILC command which require the terminating semicolon (ie: @B, @N, and @Z statements). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 4-54 Customizing MAGNUM - Display Files/MILC Commands Advanced MILC Command Usage - Enhanced Indirect Addressing Enhanced Indirect Addressing Indirect addressing was explained on the preceding pages. Now we'll introduce what we call "Enhanced Indirect Addressing". If you're familiar with the C programming language, you know about the ++ and -- operations on a variable (ie: x++, --x, etc). We've incorporated a similar operation in Enhanced Indirect Addressing. By way of example, here's how Enhanced Indirect Addressing works: @U[+5] -- Increments the contents of @N5 prior to processing the statement. If @N5 had the value 15, then this statement would be identical to the statements: @N5=(N5+1); @U16 @U[-5] -- Decrements the contents of @N5 prior to processing the statement. If @N5 had the value 15, then this statement would be identical to the statements: @N5=(N5-1); @U14 @U[5+] -- Increments the contents of @N5 AFTER processing the statement. If @N5 had the value 15, then this statement would be identical to the statemnts: @U15 @N5=(N5+1); @U[5-] -- Decrements the contents of @N5 AFTER processing the statement. If @N5 had the value 15, then this statement would be identical to the statements: @U15 @N5=(N5-1); Note that @U[+5] could also be denoted as @U[+N5]. The concept of the + and - symbols either prefixing or suffixing the value stems from the ++ and -- operations in the C programming language. The new, enhanced ability to increment/decrement the contents of the @Nx variable being referenced within brackets would replace the following: @N5=0; @P1 @U[5] @N5=(N5+1); @B1(N5<67); with: @N5=0; @P1 @U[5+] @B1(N5<67); and of course, both of the above methods are shorthand for: @U0 @U1 @U2 . . . @U66 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-55 Advanced MILC Command Usage - Enhanced Indirect Addressing The ability to increment/decrement the contents of the @Nx variable being referenced in brackets also has one additional feature - the ability to specify both a prefix and a suffix! For example: @N5=1; @U[+5+] would be the equivalent of: @N5=1; @N5=(N5+1); @U2 @N5=(N5+1); In either case, the value of @N5 would be 3 when complete. Other valid examples: @U[5] @U[5+] @U[5-] @U[+5] @U[-5] @U[+5+] @U[+5-] @U[-5-] @U[-5+] Of course, these are not limited to @Ux variables, nor is the bracket reference limited to 5 - we merely chose this for illustrative purposes. Here's one additional example which demonstrates how to display the entire character set using what you've just learned: @N5=0; @P0 @\[5+] @B0(N5<256); And as a friendly reminder, indirect addressing (the use of '[' and ']') is NOT available for MILC variables appearing within parenthesis or on the right side of an assignment (=) statement. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank MAGNUM's Sysop Console Page 5-1 Intro MAGNUM's sysop console (the parent process) - the program entitled MBBS, should be blown up to a full-size screen for this chapter. You've probably already guessed at certain portions of the display, but basically MAGNUM's sysop display shows you a brief summary of what is going on in the system and on each node. For instance, the date and time displayed above the [Node01] line is always accurate. On the same line, you will see numbers on the far right if/when someone is logged on. Assuming the 4-node version (node 4 is the conosle/local node), if there is a user on node 1 and 2 for example, you will see "1,2" (without the quotes). If you're logged on locally, you will see <4> (in angle brackets to indicate "local logon") if you log on locally with the command: "* logon". However, if you log onto node 2 locally (for example) with: "* logon 2" command, you'll see <2> instead. Note that your serial# appears on the same line as the "Node01" title. On the line containing the "Magnum BBS (r) " and serial number information, a red asterisk (*) will now appear right after the "Magnum BBS (r) " portion to indicate if anyone has entered any mail to the Sysop since the Sysop's last logon. The red asterisk will remain until the Sysop logs on. Once the Sysop logs on, the the asterisk will disappear regardless of whether the Sysop reads any mail or not. The red asterisk will re-appear if new mail addressed to the Sysop arrives. The Sysop display console (the MBBS.EXE program) displays 3 sessions at a time. Initially, the sessions for Node01, Node02, and Node03 are displayed on the screen. To see other sessions, use the TOP command. In other words, if you have our 9-node version (8 comport + console), you could enter the command "4 TOP" (without quotes) and Node04 would be brought to the top of the display - sessions Node04, Node05 and Node06 would be displayed. In the 4-node version (3 comports + console), "2 TOP" and "1 TOP" are the only acceptable commands. The first line of each shows whether the line is ACTIVE (waiting for calls or announce only), or INACTIVE (shut down or not operating), or who is on. If you just started the MBBS.EXE program, the next 2 lines of each screen will be blank, otherwise, if someone is online, line 2 will show some brief info about them, while line 3 will show where they are in the system and what they're doing. If no one is on an active line, the system will show who was last on, when they called and how long they were on for. By the way, the "how long they were on for" (in minutes) will change to 0 (zero) if someone tried to call the board but didn't successfully log on since the last successful caller, or if carrier was dropped. The "Command => " prompt is where you interact with MAGNUM to do things like turn the bell on/off, force a user off, shutdown the bbs, turn on/off the printer, etc. You can only get to this prompt by hitting one of 11 keys: a digit (0 to 9) or an asterisk (*). If you press a digit, it should be the digit of the node you wish the command to apply to (or the first digit of a 2-digit node). If you press *, the command applies to all nodes (except local logon). IMPORTANT: When entering a command, MAGNUM assumes high-priority and DOES NOT process incomming calls or any other obligations MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-2 MAGNUM's Sysop Console Intro until you have finished entering your command. Therefore, USE THE COMMAND PROMPT AS QUICKLY AS POSSIBLE!! If you hit a digit or * and walk away, you have effectively frozen your BBS - currently running sessions are not affected but no more incoming calls or events (ACE commands) will be processed! The remainder of this chapter will deal with the commands you can enter as sysop at MAGNUM's Sysop Command prompt. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-3 The Bell, Forceoff, Switch and Info Commands x bell|nobell Sometimes the sound of bells can become rather annoying. MAGNUM sends a BEL character to the remote user when it doesn't like something, or when it needs to alert the remote user of something. This BEL is also echoed at the sysop console. To turn it off for, say Node01, you would enter: 1 NOBELL To turn it on, enter: 1 BELL Note that turning the bell on and off does not affect the remote user's end. The remote user will always hear the bell. x forceoff You can FORCE a user off anytime you wish. All this command does is emulate a dropped carrier on whatever node you use it on. The user could call back immediately if they wanted to. To force a user off of node 2, for example, you would enter the command: 2 forceoff The system will act as though the user dropped carrier (hung up), and reset itself for the next caller on that node. x switch You can snoop on any session in progress by switching to it. When a session starts (with the exception of a local logon), the session starts at your end as an icon. For example, if you wanted to snoop on the user on node 1, you would enter: 1 Switch This would blow up the icon into a window or full text screen (depending on how MSESSION.EXE is marked to start). You can also switch to that session by double clicking the mouse pointer on that session's icon. Snooping on someeone performing a file transfer (ie: making their session the foreground process so that you can see what they're doing) will result in a temporary boost in priority to that foregroung process! This can also slow down other sessions! Remember that anytime you snoop on a session, it will receive a temporary boost in priority by OS/2, thus causing a slight slowdown for all other sessions (this is more of a concern for users of OS/2 1.x than 2.x). File transfer does large block writes and reads to and from your modem (ie: 1K blocks) which can cause slowdown in performance of the other sessions if you snoop on someone doing a file transfer (make them MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-4 MAGNUM's Sysop Console The Bell, Forceoff, Switch and Info Commands the foreground process). Because of this temporary boost in priority for foreground processes, we recommend running your local (console) node at a priority less than that of any other node. x Info The INFO command shows information about NODEx. It shows whether the bell is on or off (beeping echoed to console), whether the printer is enabled or disabled, whether normal or announce-only mode is used. Also shown is the serial number and the node numbers of all active ports (nodes), the device name associated with NODEx and whether or not a SHUTDOWN is scheduled for node x. If a shutdown is scheduled for all nodes it will be shown here. As always, whenever you are executing a command, the parent "freezes" (won't respond to incoming calls) until the command is completed. In this case, a display is presented and you are prompted to strike a key to clear the display - the parent remains "frozen" until you clear the display by striking a key. Note that the display for the "info" command takes place on the bottom 6 lines of the display screen/window. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-5 The "* auto" and "* noauto" commands "* auto" and "* noauto" * AUTO - Automatically switches to a session when a remote session is started (regardless of node). This command might be considered useful for those sysops running a single-node BBS, whereas those running a multi-node BBS might find this command to be disruptive. * NOAUTO - As before, only a local logon will be switched to automatically, all other nodes must be switched to by either the "x switch" command or by double clicking on the session's icon with the mouse pointer. This is the startup default. To make "* AUTO" the default, you can have it as an "immediate" command in your ACE file. Note: Refer to the chapter on ACE (automatic command execution) - Magnum's event handler. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-6 MAGNUM's Sysop Console The level, print and lockout commands x level yyyy While someone is actively online, you can change their security level with this command. For example, if you wish to change the user on node 1 to a security level of 50, you would enter the following: 1 LEVEL 50 MAGNUM would then give you a message as to the success of the command. x print MAGNUM automatically keeps a log of activity for each node in a file called ACTIVITY.x (where x is the node number in which activity is being recorded). This file grows substantially with time so you'll want to back it up if desired and delete it from time to time. Note that if you view the activity log from MAGNUM's sysop menu when you're logged on, you will be viewing the log backwards (most recent activities first). You may elect to simultaneously log to your printer what is happening on a given node as well as to this activity-log file. To start doing this for node 1, for example, enter: 1 print To turn it off for node 1, enter: 1 noprint If running MAGNUM as a multinode system (more than 1 active node), and printing to the same printer for both nodes, you need to use the spooler. Be advised the spooler uses MUCH RAM MEMORY, and in some cases, there may not be enough left to run MAGNUM as ancticpated. This depends on how much RAM memory you have in your system to begin with. x lockout You can LOCK OUT any user currently online. For example, if you decide the user on node 2 is abusing the system, you can lock them out with: 2 lockout The user will be denied subsequent access. To prevent abusers from calling at all, consider running Magnum as a "closed" system. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-7 The active, time, announce/normal, and logon commands x active|inactive If you have an active node running that you'd like to make inactive, or if you have an MBBSINIT.x file defined for a node but that node is currently not active, this command will let you toggle the current state of the node to/from active/inactive. For example, to make node 1 inactive, enter the command: 1 inactive To make node 2 an active node, enter the command: 2 active Note that the "inactive" command takes place immediately if there is no one online on that node at the time you issue the command, otherwise the command takes place after the current caller logs off. time+nnn | time-nnn You can increase or decrease the amount of time a user has left for their session with this command. nnn is the number of minutes you wish to increase or decrease their time by. For example, if you wish to increase the time for the user on node 1 by 20 minutes, enter the command: 1 time+20 If you wish to decrease the time for the user on node 2 by 10 minutes, enter the command: 2 time-10 Note that this command is processed by the minute. In other words, the effect of this command may not be realized for up to 1 minute. NOTE: Changing the user's time via the Sysop Utilities (user area) will not work if the user being changed is currently logged on. You MUST use the "x TIME+nnn" or "x TIME-nnn" commands for a user who's currently logged on. announce | normal This command changes a node from normal BBS operation to announce-only, and vice versa. If you wish to change node 1 from normal BBS operation to announce-only, simply enter the command: 1 announce Note that by doing so, MAGNUM will answer incoming calls as usual but will display the file ANNOUNCE.1 (for node 1, ANNOUNCE.2 for node 2, etc) to the caller and then hang up. MAGNUM will continue to be in MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-8 MAGNUM's Sysop Console The active, time, announce/normal, and logon commands announce only for whatever node you told it to announce to until you change it back with the following command: 1 normal Note that the ANNOUNCE.x file should not have any color or ANSI sequences in it since no one is allowed to log on, therefore, you don't know if your caller has color capability or not. The file(s) ANNOUNCE.x should be placed in the PROGRAM DIRECTORY. - - DO NOT SET YOUR LOCAL NODE AS ANNOUNCE-ONLY! Every time an ANNOUNCE.x is sent to the remote caller, Magnum logs this in a file called ANNOUNCE.LOG in your PROGRAM DIRectory. * logon As mentioned earlier, you can log on locally (without a modem) by entering the command: * LOGON Currently, you will need to have a MBBSINIT.4 file in order to do this. You can accomplish this by copying STARTUP.1 to STARTUP.4, then changing the NODE parm to 4 and recompiling with the MAKEMBBS.EXE program. If you have the 9-node version of Magnum, STARTUP.9 is your local node. Alternately, you may log on to any of the logical nodes locally with: * LOGON x Where 'x' is the node# of the logical node you wish to log on to. You will still be on physical node 4 (console for 4-node version) or node 9 (console for 9-node version), etc. With this alternate method, Magnum is simply using the MBBSINIT.x file for all of its information rather than the MBBSINIT.4 or MBBSINIT.9 file. Because each MBBSINIT.x files can be its own separate BBS (with its own databases by making the session directory unique from the other nodes), this method of logging on locally allows you to be online as though you were on node x. It's also a great way to test your MILC files if you have different display files for different nodes. Note that node 'x' does not have to be "active", nor do you have to wait until someone on the real node 'x' logs off. You may log on to node 'x' locally anytime. NOTE: In the MBBS.EXE display screen, on the far right of the same line as the date and time, MBBS will show you the node number(s) of the node(s) currently having a caller logged on. For example, if callers are on nodes 1 and 3, MBBS will show 1,3. If your console node is node 4 (4-node version) and you log onto node 4 (* LOGON), MBBS will show 1,3,4(4). The 4 (in the 4-node version) indicates console node, and the parenthesized number next to it shows logical node. If you logged on to node 2 locally (ie: * LOGON 2), then MBBS would show 1,3,4(2). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-9 The endnow, end, shutdown and msg commands * endnow You can end MAGNUM BBS immediately by entering the command: * endnow This will cause MAGNUM to emulate a dropped carrier on all nodes currently in session, then finally end the program and return back to the OS/2 command line or to the OS/2 start programs menu. * end To shut down MAGNUM BBS after the last caller's session ends, enter the command: * end Note that if 2 or more people are online, MAGNUM will deactivate the comport of each line after each respective session ends, thus disallowing further calls. When the last user logs off, MAGNUM shuts down and returns you to the OS/2 command line or to the OS/2 start programs menu. x shutdown | * shutdown You can tell MAGNUM to shut down any or all nodes with the SHUTDOWN command. Simply enter the shutdown command followed by the time you wish MAGNUM to shut down that node (or all nodes). The time must be in 24-hour format. For example, assuming it is 2:00 PM now, and you wish to shut down MAGNUM at 2:15 PM, you would enter the command: * shutdown 14:15 MAGNUM would then send the following message to all users on any of the nodes: << System going down in 15 minutes >> MAGNUM will send the "system going down" messages every 5 minutes from this point until 5 minutes are left, then at 1 minute intervals. When the time is reached, MAGNUM shuts down all nodes and terminates itself regardless of who's online or what they're doing. Note that MAGNUM doesn't send any "system going down" messages until 30 minutes before shutdown is scheduled. It then sends another at 20 minutes, then 15, 10, 5, 4, 3, 2, and 1 minute remaining. Note that if there is less than 20 minutes to shutdown and no one is on a particular node, MAGNUM shuts down that node anyway. Instead of shutting down all nodes, you can shut down individual nodes by using the node number instead of the *. For example, you can shut down node 2 by entering: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-10 MAGNUM's Sysop Console The endnow, end, shutdown and msg commands 2 shutdown 05:28 This will schedule node 2 to shutdown at 5:28 (AM). MAGNUM will send "system going down" messages to this node starting 30 minutes prior to shutdown. If no one is on the node within 10 minutes of shutdown, MAGNUM will shut the node down anyway. To reactivate a shut-down node, for example, node 2, enter the following: 2 active To cancel a shut-down in progress (ie: node 2 will be shut down in xx minutes), enter the following: 2 shutdown cancel This is a powerful command and will not pay any attention to what users are doing. When the shutdown time reaches it's scheduled time, all nodes (or the particular node) being shut down will emulate dropped carrier! x msg "string" | * msg "string" The MSG command sends a quick and dirty message from the console to any or all ports. "string" (without quotes) is the contents of your message. For example, to send a quick message to node 1, simply enter: 1 msg Please update your telephone number! To send a quick message to all nodes, simply enter: * msg I'm starting a group conference - please go to the GROUP CHAT MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-11 miscellaneous commands If you're running MBBS as a fullscreen text app, or you've blown up it's window to full size, the commands we've just described above will appear on the bottom 5 lines of the MBBS display screen. These are the most commonly used commands. There are a few other commands which you'll probably use less often which we'll cover now. Although premature for you to understand the following commands, you should scan them over for now, then return here for a better understanding once you complete the chapter on ACE (automatic command execution) - Magnum's event handler. Executing another program from within MBBS You can execute another program from within MBBS.EXE by starting the command with the * character, and then providing the program name and it's parameters within doublequotes (the " character) followed by a comma and one of WAIT, NOWAIT or DETACH. For example: * "program.exe parms",WAIT This would run "program.exe" while MBBS WAITs for it to complete, then returns back to normal BBS operation. A program run with the WAIT parameter causes MBBS to save the present screen image, and halt all further MBBS execution (will not have any effect on currently running sessions) until the program completes - at which point the screen will be restored and normal BBS operation will resume. Running a program with the NOWAIT parameter causes the program you specify to run concurrently with MBBS - normal MBBS operation is resumed immediately and the present screen image is not saved. Any program started in such a fashion must NOT write to the screen (or stdin or stdout), or expect any input from the console (or keyboard). If the program you're running does write to the screen, you can redirect it's output with the > character. For example, to redirect all output for the program, you might enter a command such as: * "program.exe parms 1>nul 2>nul",WAIT which redirects stdout (handle=1) and stderr (handle=2) to nul (a nonexistent dummy file name used by OS/2). Just a simple redirection of ">nul" which was good enough for DOS (redirected stdout and stderr to nul) will not work with OS/2 - instead ">nul" to OS/2 means the same as "1>nul" which will only redirect stdout but not stderr. Running a program with the DETACH parameter is identical to running it with the WAIT parameter except that the program will continue to run even if MBBS terminates. The program can do screen I/O only via VioPopUp() calls. The "* REFRESH" command In the event you've run another program with the NOWAIT or DETACH parameter and forgot to reroute it's output, thus causing it to write to the screen, you can refresh the screen with this command - it won't be MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-12 MAGNUM's Sysop Console miscellaneous commands the last screen but it will at least get rid of the output from the externally running program. The "* ACE INIT" command This command will cause MBBS to re-read the MBBS.ACE file, over-writing any ACE commands that were queued for timed execution. When this command is issued, any ACE "immediate" commands contained in the file will be ignored - this insures that duplicate copies of programs will not be started. All previously stored ACE commands will be purged prior to re-reading the MBBS.ACE file. The "x TOP" command Although we touched on this command earlier, this command will basically be used by those running our 9-node system (8 comports + console) or 17-node system (16 comports + console). Because MBBS only shows 3 consecutive nodes on the sysop display at any given time, you can bring any node to the top of the display with this command. For example, the command "5 TOP" will display nodes 5, 6 and 7 on the sysop console. In the 4-node version, "2 TOP" and "1 TOP" are the only acceptable commands. In the 2-node version, the TOP command is unavailable. In the 9-node version, "X TOP" can be issued where X is a value from 1 to 7. In the 17-node version, X can range from 1 to 15. In the 9-node and 17-node versions, Magnum will automatically change the top display node itself on an incoming call that is not already one of the 3 in the current display. For example, if your TOP node is 5 (ie: displaying node information for nodes 5, 6 and 7), and a caller calls on node 2, Magnum will internally issue a "1 TOP" command resulting in nodes 1, 2 and 3 being displayed. In other words, Magnum issues an "x top" command where 'x' is the lowest node number which would also include display of the new caller. The 17-node version allows the use of the TOP command when in condensed mode, whereas all other versions disregard the TOP command in condensed mode (see "* CONDENSE ON" and "* CONDENSE OFF" commands). The "* SYSBELL" command Sometimes it can become annoying to hear the sounds Magnum makes when a caller's session is about to be started. The "* SYSBELL OFF" command will deactivate these sounds, likewise, the "* SYSBELL ON" command will turn them back on again. Do not confuse this command with the NOBELL/BELL commands which apply to the session - SYSBELL only applies to the Sysop console (MBBS.EXE) whereas NOBELL applies to MSESSION.EXE. The "* HELP" command When running MBBS.EXE as a fullscreen text app (or as a maximized text window), the sysop commands appear at the bottom of your screen/window in the last 4 lines of display. However, there isn't room for all of the commands to appear in the last 4 lines, therefore, "* HELP" will display the next set of 4 lines summarizing additional commands. Each time you enter "* HELP" (or "x INFO"), the HELP display at the bottom MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-13 miscellaneous commands will alternate. The "x BLOCKWRITE" command The "x BLOCKWRITE" command enables/disables block writes for node x. For example, the command "2 BLOCKWRITE ON" would enable blockwrites for node 2, while the command "2 BLOCKWRITE OFF" would disable blockwrites for node 2. The "* COLOR" command This command doesn't affect BBS operation, it simply sets the colors used by MBBS.EXE which you might rather use than the default colors. The syntax is "* COLOR UPDT MSG EXIT", where: UPDT is the color of the update information printed on the sysop console for the three nodes being currently displayed. MSG is the color of any messages printed just below the "Command =>" prompt. EXIT is the color Magnum will reset your screen to upon exit. The value of the colors for all three parms can be one of 1 to 7 or 9 to 15 according to the following color table: 0 - UNUSED 8 - UNUSED 1 - blue 9 - bright blue 2 - green 10 - bright green 3 - cyan 11 - bright cyan 4 - red 12 - bright red 5 - magenta 13 - bright magenta 6 - brown 14 - yellow 7 - white 15 - bright white For example, the command: * COLOR 11 12 7 would set the UPDATE color to 11 (bright cyan), the MSG color to 12 (bright red), and the EXIT color to 7 (white). The settings used in this example also happen to be the default color settings. As with all other default system settings, you can put this command as an 'immediate command' in your MBBS.ACE file with the parameters to match whatever colors you choose. The "* CONDENSE ON" and "* CONDENSE OFF" commands The condensed mode of operation is mainly for those using the 9-node version of Magnum BBS or higher. Although it will also work for the 4-node version. The "* CONDENSE ON" command tells MBBS to display only the state of all nodes (ie: ACTIVE, INACTIVE, who's on the node, etc). In other words, instead of each node having 3 text lines of display, MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-14 MAGNUM's Sysop Console miscellaneous commands each node will only have 1 text line of display. The "* CONDENSE OFF" command returns MBBS to the default 3 text lines of display per node. The advantage of 1 text line per node is that you can see who's on all nodes without having to issue a "x TOP" command. The disadvantage is that you don't know what the users of each node are currently doing. This command is geared for the 9-node version of Magnum and higher. Users of the 4-node version will probably not have much use (if any) for this command. Users of the 17-node version can issue the "x TOP" command for consecutive display of any 9 nodes. The "* PRTY class level" and "* PRTY ?" commands The priority class and level of MBBS.EXE (the Magnum PARENT program) can be set with this command. Note the syntax uses the space character to delimit the parameters (no commas). The priority class can range from 1 to 4 where 1=Idle Time Class, 2=Regular Time Class, 3=Time Critical Class, and 4=Foreground Class. The level within the class can range from 0 to 31 where 0 is the lowest level within a class (lowest priority) and 31 is the highest level within a class. Unless you are a system administrator or other individual experienced in fine tuning systems with priority levels and classes, this should remain at Class 2, Level 0 (* PRTY 2 0). Note that you can query the current priority class and level with the command "* PRTY ?". NOTE: Do not confuse this command with the PRTY_CLASS and PRTY_LEVEL parameters in your STARTUP.x file(s). Those are for the priority classes and levels of MSESSION.EXE (individual user sessions). The "* PLAY x" command and Recording a Session for later playback This command is similar to the "* LOGON x" command but "plays back" a previously recorded sysop session. The 'x', although optional, is the node#, and if not supplied will default to the console node (node 2 in the 2-node version, 4 in the 4-node version, etc). To record a session for playback, use the "* LOGON x" command and log on as usual (you cannot record a session from any node other than the console node). Log on as ID //0 (sysop) and note the double slash instead of a single slash. When you've logged on this way, you'll get a message stating "Invalid ID" and a note that the session is being recorded. When re-prompted for your ID, proceed to log on as usual. Everything will be recorded to a file for later playback with the "* PLAY x" command. Note that the 'x' in the LOGON and the PLAY command determines which file number to record or play back. NOTE: When recording a session, DO NOT stop any displays with <Ctrl-X> or the spacebar character! DO NOT run external programs requiring anything other than command-line arguments (no interactive pgms). The purpose of recording a session is to automate packing of the databases with an MBBS 'ACE' command, where "* PLAY x" would be the ACE command. See the chapter on ACE (Automatic Command Execution - Magnum's Event Handler). The "x YELL" and "x NOYELL" commands Although Magnum abides by the Sysop paging hours in your STARTUP.x MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-15 miscellaneous commands file(s), you can override this with the YELL and NOYELL commands (where 'x' is the node number). For example, to turn off the ability for a remote user to page the Sysop on node 2, issue the command "2 NOYELL". To turn on the ability to page the Sysop on node 2, issue the command "2 YELL". Note that when NOYELL is issued on a node, it disregards Sysop paging hours and dissallows the ability for the Sysop to be paged. When YELL is issued, Magnum abides by the Sysop Paging hours specified in the STARTUP.x file for node x. The "x ONHOOK" and "x OFFHOOK" commands You can send ONHOOK and OFFHOOK commands to your modem. By sending an OFFHOOK command, it's like physically lifting your telephone off the hook and letting it sit there (any callers will get a busy signal). If you issue an ONHOOK command, it's like hanging up the phone (the modem is ready to receive calls). NOTE: Unless you have an external modem with lights that indicate whether your modem is onhook or offhook, we suggest you avoid the use of these commands. The "* RMAIL node:userid" command This command starts the RMAIL process (Magnum-to-Magnum remote mail exchange) with another Magnum BBS system. Refer to the chapter on Magnum-to-Magnum Remote Mail. The "x CALLS MAIL" and "x CALLS ALL" commands The "x CALLS MAIL" command sets node x such that only MAIL accounts will be granted access to the system on node x. Any USER accounts will be denied access. Optionally, the file NOTMAIL.x in your PROGRAM DIRectory (if it exists) will be displayed to a USER prior to denying access when the node is in 'mail only' mode. The "x CALLS ALL" deactivates "mail only" mode. When this command is issued for node x, node x will accept ALL caller types (MAIL and/or USER). The "* LOGOCOLOR x" command where 'x' is a number ranging from 1 to 15. The color value is the same as the values of the * COLOR statement. This command changes the color of the logo appearing at the top of the screen. This command is used if the default color does not show up on monochrome screens. The "* FRAMECOLOR x" command where 'x' is a number ranging from 1 to 15. The color value is the same as the values of the * COLOR statement. This command changes the color of the frames appearing around the node displays. This command is used if the default color does not show up on monochrome screens. The "* ERRLOG ON|OFF" Command MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-16 MAGNUM's Sysop Console miscellaneous commands If you specify ON, any warning or error messages will be logged to the file MBBS.ERR in your program directory. Note that once ON is specified, the file MBBS.ERR remains open until the BBS is shut down (* ENDNOW), even if you specify OFF. Also note that whenever you restart your BBS (MBBS.EXE), it will delete the MBBS.ERR file upon startup. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-17 CHATting between SYSOP (you) and a USER via the Console To chat with a remote user, simply SWITCH to their session (make their session the foreground process). When their session is in the foreground, press your <F7> key and both you and the user will be placed in SYSCHAT mode (Sysop Chat with User). Note that if the user is entering a message at the time you press <F7>, the chat will be delayed until the user finishes message entery, otherwise chat will take effect at the very next system prompt the user gets. To end the chat, simply press your <F7> key again. Note that all text which transpires between you and the remote user during SYSCHAT will be logged to the SYSCHAT.LOG file in your SYSOUT directory. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-18 MAGNUM's Sysop Console Displaying a File with <F6> Pressing the F6 function key during a user's session (with that session in the foreground) will cause a system prompt for a filespec to display. This can be used for a variety of purposes such as displaying a MILC-containing file to perform a certain task (such as calling a .mex program to upgrade a user online). The filespec you enter will be processed and displayed as though it were a system file (such as a newsletter). This function can only be invoked by switching to an online user's session and pressing the F6 key at the console. In that a prompt for a filespec results (rather than a predetermined filename assigned to a function key) system security is maintained against someone snooping on a session at the console and accidentally pressing that function key. Note that neither the prompt for the filespec or your entry of the filespec name will be displayed at the remote user's screen. The filespec entry can be up to 100 characters in length. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-19 TEST Mode (Testing your modem) The "x TEST" command This command will rarely be used. However, setting up a BBS for the first time can be frustrating. BBS software must be able to interact with your particular modem. Sysops are not expected to be modem experts, nor should they have to be. Sometimes, due to the nature of BBS and modem relationships, problems will develop during initial setup. Therefore, we've included a TEST mode for any problems which may be encountered when setting up a new modem. The syntax of TEST mode is "x TEST". For example, to put the modem on node 1 into test mode, you'd enter the following command on the Sysop command line: 1 TEST Once in TEST mode, brief instructions will appear which are all self explanatory. Basically, you'll start with the /INIT command and watch for the digit 0 (zero if using numeric result codes [V0]) or the word OK (if using verbose result codes [V1]) being displayed after each STARTUP string sent to your modem. If you don't get a 0 or OK back from a particular string, it indicates a problem with that string. Contact Gilmore Systems for further information regarding TEST mode. CAUTIONS: - DO NOT USE THIS MODE TO DIAL OUT WITH. THE RESULTS WILL BE UNPREDICTABLE! - AS WITH ALL OTHER SYSOP COMMANDS, MBBS.EXE WILL REMAIN IN A "FROZEN" STATE UNTIL YOU ARE THROUGH WITH TEST MODE (ie: will not recognize incoming calls). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-20 MAGNUM's Sysop Console Icon Control Commands The "x TITLE new title string" command Syntax: x Title New-Title Replaces the title name placed above the icon when running MSESSION.EXE for node x. A string of up to 32 characters can be used. The "x ICON" command Syntax: x ICON [d:][\][path]filename[.ext] Assigns an icon file to be associated with MSESSION.EXE for node x. During our testing, this works fine with OS/2 1.3, however, we cannot seem to associate an icon with MSESSION.EXE in OS/2 2.0 which we feel is probably a bug in the OS. If any of you have any luck in this area, please let us know what fixes to the OS (if any) you've installed, and what steps you've taken. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-21 Program Control Commands The "x PGM pgmname.exe" command Syntax: x PGM [d:][path]pgmname.exe Where 'x' is one of your nodes, PGM is the keyword, and pgmname.exe is the name of the program to be started (executed) when a caller calls. This is designed exclusively for those using the Magnum "Language Replacement Module" (it is not meant to start any other programs). For example, if you converted the English text within MSESSION.EXE to German and renamed the program to MSES_GER.EXE, and/or did the same with French and/or Italian. For example, if you have MSESSION.EXE as your English module, MSES_FRE.EXE as your French module, and/or MSES_GER.EXE as your German module, and/or MSES_ITA.EXE as the Italian module, etc, then you might consider the following (assume 9-node version for this example): 1 PGM MSESSION.EXE 2 PGM MSESSION.EXE 3 PGM MSES_GER.EXE 4 PGM MSES_GER.EXE 5 PGM MSES_FRE.EXE 6 PGM MSES_FRE.EXE 7 PGM MSES_ITA.EXE 8 PGM MSES_ITA.EXE 9 PGM MSESSION.EXE The above will assign MSESSION.EXE (English) to nodes 1, 2 and 9. The German module will be assigned to nodes 3 and 4, French to 5 and 6, Italian to 7 and 8. This is merely an example; you can assign whichever programs you wish to whatever nodes you wish. Furthermore, to make this automatic, simply place these commands in your MBBS.ACE file (example): *,1 PGM MSESSION.EXE *,2 PGM MSESSION.EXE *,3 PGM MSES_GER.EXE *,4 PGM MSES_GER.EXE *,5 PGM MSES_FRE.EXE *,6 PGM MSES_FRE.EXE *,7 PGM MSES_ITA.EXE *,8 PGM MSES_ITA.EXE *,9 PGM MSESSION.EXE If you're using a single dial-up line (node1 for example), you might consider having German available from 00:00 to 12:00 and English available from 12:01 to 23:59 (as an example); the commands in your ACE file would be: 0123456,00:00,1 PGM MSES_GER.EXE 0123456,12:01,1 PGM MSESSION.EXE MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 5-22 MAGNUM's Sysop Console Program Control Commands --> NOTE <-- The program (pgmname.exe) MUST be located in your PROGRAM DIRectory! You must NOT supply any information other than the program name and extension (no path or drive information allowed). The extension MUST be .EXE (.CMD, .COM, .BAT, etc are NOT acceptable)! - x PGMINPUT * | [%com%] [%baud%] [%device%] [parm1 ...parmx] When using the "x PGM pgmname.exe" feature, you can use the "x PGMINPUT" command to pass whatever input you wish to your pgmname.exe. If you use %com% as part of this input, it will be replaced with the comport handle prior to starting pgmname.exe. Likewise, %log% will be replaced with the activity log handle (write only), %baud% will be replaced with the baud rate (DCE), and %device% will be replaced with the device name. Alternately, you can use "x PGMINPUT *" to revert back to the parameters expected by MSESSION.EXE or any derivative of MSESSION.EXE you may have created with the Language Replacement Module. - Although the above "x PGM pgmname.exe" command within MBBS.EXE is one solution to the LANGUAGE problem, MSESSION.EXE offers another solution which OVER-RIDES the MBBS.EXE solution: When MSESSION.EXE starts, it now checks for the presence of a file in your PROGRAM DIRectory by the name of LANGUAGE.LST and if it finds it, prompts you for a language, exits, and restarts the new language module - without breaking the connection! The format of LAGNUAGE.LST (via example) is as follows: ENGLISH (MSESSION.EXE *) FRENCH (MSES_FRE.EXE *) GERMAN (MSES_GER.EXE *) ITALIAN (MSES_ITA.EXE *) SPANISH (MSES_SPA.EXE *) The format is simple: Name of the language, followed by the program name and its parameters in parenthesis. For our purposes, the paremeters to MSESSION.EXE (or any derivative created with the Language Replacement Module) shall have its parameters denoted by the * character. When Magnum reads this file, it will present it to the user without the program names, and will provide a language "menu" (selection) based on your file. - If the file LANGUAGE.LST exists, it applies to ALL NODES! If you do not want ALL nodes to prompt (ie: you only want nodes 2 and 3 to prompt, but none of the others), then do NOT create a LANGUAGE.LST file! Instead, create LANGUAGE.2 and LANGUAGE.3 following the same format of the the LANGUAGE.LST file. In other words, Magnum first looks for LANGUAGE.LST - if it doesn't find it, it then looks for LANGUAGE.x (where 'x' is the node being called) - if it doesn't find that, no further looking is done, the session proceeds as usual! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems MAGNUM's Sysop Console Page 5-23 Program Control Commands - External Menus are highly recommended when using different languages! The menus presented to your callers will be the dynamically built menus as defined in your STARTUP.x file(s) unless you over-ride these with external menus! Use the @V94 MILC variable to query which language module has been loaded and then act accordingly. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank Back to Display Files & Subdirectories Page 6-1 The PROGRAM DIRECTORY *--->>> This Chapter is to be used in conjunction with chapter 2 <<<---* ****************************************************************** NOTE: * The main files (but not all files) for Magnum BBS are * * outlined here. ALL files are briefly explained in chapter 2. * * Remember, if a file listed here (or in chapter 2) is NOT found,* * it is OPTIONAL (ie: used only if it exists). THIS CHAPTER IS * * TO BE USED IN CONJUNCTION WITH CHAPTER 2. * ****************************************************************** Within the PROGRAM DIRECTORY, the following files should be found: MBBS.EXE - The main (parent) program for MAGNUM BBS. This is the program that you will start in order to start the BBS. MSESSION.EXE - The child program that MAGNUM (mbbs.exe) calls for each session. PUTFILES.EXE - The child program that MAGNUM (mbbs.exe) calls for sending files when a user chooses the [D]ownload option. GETFILES.EXE - The child program that MAGNUM (mbbs.exe) calls for receiving files when a user chooses the [U]pload option. NOTEs about GETFILES.EXE and PUTFILES.EXE: Monitoring of Carrier has been re-established for file xfers - this has caused some problems in the past (version 1.0x of Magnum, mainly on IBM PS/2 machines with EE) and has been removed ever since. If monitoring of carrier is causing a problem for you, you can remove (or implement) this monitoring of DCD (data carrier detect) by setting the following ENVIRONMENT variable PRIOR to starting Magnum (mbbs.exe) on the OS/2 command line (or in a .CMD file that starts Magnum): SET DCDXFR=FALSE (turns off monitoring of DCD for file xfers) SET DCDXFR=TRUE (turns on monitoring of DCD for file xfers) If the environment variable DCDXFR is not found (ie: not defined), the default is to turn ON monitoring of DCD for file xfers (just as though you've defined SET DCDXFR=TRUE). Also, for your convenience, any of the following parms are all acceptable: To turn OFF monitoring of DCD for file xfers: SET DCDXFR=FALSE or SET DCDXFR=OFF or SET DCDXFR=NO or SET DCDXFR=N or SET DCDXFR=0 To turn ON monitoring of DCD for file xfers: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-2 Back to Display Files & Subdirectories The PROGRAM DIRECTORY SET DCDXFR=TRUE or SET DCDXFR=ON or SET DCDXFR=YES or SET DCDXFR=Y or SET DCDXFR=1 MAKEMBBS.EXE - The configuration compiler/de-compiler. This is the program that compiles your STARTUP.x files into MBBSINIT.x files, or de-compiles your MBBSINIT.x files into STARTUP.x files. MBBSEXEC.EXE - This is the MBBS executive progam utility for sysops which not only simplifies maintenance, but also provides a very powerful, flexible programming language with which the Sysop of a Magnum BBS can use to define his/her maintenance needs. RJEMONIT.EXE - This is a daemon process which monitors RJE jobs started by Magnum. A daemon process is a program which runs in the background continually until your computer is either shut off or rebooted. A daemon process cannot be selected or "switched to" because it's running as a detached process. A separate copy of RJEMONIT.EXE is invoked only once for each node. The original invokation happens only when the 1st user on any node chooses the [L]ist/Execute function of the RJE section, or the first time the @E1 command is encountered. Once it's started, Magnum knows it's running and will never start it again unless the system has been rebooted. RJEMONIT.EXE will be invoked once for each node, and only if the @E1 MILC command or the [L]ist/Execute function has been selected in the RJE menu for that node. The RJEMONIT.EXE program is responsible for updating the RJE database when RJE job(s) complete - regardless of whether the user is online, or even if your BBS system is running or not. STOPMBBS.EXE - These programs are used to immediately stop ALL actively & STOPRJE.EXE running copies of MBBS.EXE and LOCALBBS.EXE (LAN Local Logon Module) and their associated MSESSION.EXE programs; AND all actively running RJEMONIT.EXE programs. For more information on the use of these programs, execute the program without parms. KILLPROC.EXE - This program is used internally by Magnum, however, you may find this program of use to you too. For more information on the use of this program, execute it without parms. EMAILIN.EXE - This program places incoming Internet E-mail into the appropriate Magnum MsgBase/area. MBBSINIT.x - The output files that MAKEMBBS.EXE creates from your MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-3 The PROGRAM DIRECTORY STARTUP.x files. No node can run without a matching MBBSINIT.x file, where x is the node number. STARTUP.x - The human-readable source file which will serve as input to the MAKEMBBS.EXE program. MAKEMBBS.EXE converts these files to MBBSINIT.x files. ANNOUNCE.x - A simple text file (where x is the node number the file will be used on). This file contains an announcement and is displayed when the node is in "announce-only" mode. Do not use any ANSI escape sequences or color in this file! MBBS.ACE - A text file containing Magnum ACE (Automatic Command Execution) commands. Read by MBBS.EXE upon startup. Commands in this file can be a combination of "immediate" (commands to be executed right away) and queued commands (commands to be stored for later, timed execution on certain days and times). ACE.LOG - Generated by MBBS.EXE - this file contains the log of any ACE commands which were executed by MBBS.EXE including the date and time of execution. UTILIZ.DAT - This file contains utilization information about your system. It will not exist until after your first logon. An external child (door) program is in the works which will process the data in this file. For those interested in the record layout of this file please contact us for further information. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-4 Back to Display Files & Subdirectories The SESSION DIRECTORY Within the SESSION DIRECTORY, the following files should be found: SPLITKEY.EXE - This program rebuilds *.KEY files from your USER.DAT (user database) file. The SPLITKEY.EXE program will reject all LastName's not starting with one of the following characters: - alphanumeric (A-Z, a-z, 0-9) - underscore ( _ ) character - dollar ( $ ) character If the last name of any record does not start with one of these characters, the record for this file will not be rebuilt into a key file, but the last name will change to ERRORxxxxx (where xxxxx is the ID of that user account). NOTE: If you change someone's LAST NAME, whether with MBBSEXEC.EXE or via the Sysop menu, you'll need to rerun SPLITKEY.EXE, however, you can save time by running it with the first initial of the user's last name (before & after). For example, if you change one of your user's last name from DOE to SMITH, you would run SPLITKEY twice as follows: SPLITKEY D SPLITKEY S This causes the SPLITKEY program to rebuild USER_D.KEY and USER_S.KEY files. AMMO.MAG - Refer to the chapter on Remote Mail. NOCHANGE.LST - The [E]nvironment section of the main menu (where users can change their system/personal paramters) is now configurable by the Sysop as to which parameters may/may not be changed. If you wish all parameters to be changeable (as before), then do nothing! Otherwise, create the file NOCHANGE.LST in your SESSION DIRectory. This file is an ASCII text file which contains the numbers (1 thru 27 in this release) of which parameters you do NOT want your users to be able to change! For example, if you don't want users to be able to change System compression type (choice 1) or their birthdate (choice 11), then the file NOCHANGE.LST would contain the two menu numbers as follows: 1 11 The format of the file is one menu number per text line. BADNAME.LST - This ASCII text file contains a list of UNallowable logon names - one name per line, no imbedded spaces. See the enclosed BADNAME.LST for an example. BADUPLD.LST - This ASCII text file contains a list of UNallowable filenames for upload - one name per line. Wildcards * and ? are acceptable. Note that a semicolon (;) starts a comment. In the event that a user tries to upload a file MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-5 The SESSION DIRECTORY who's filename matches one of those in this list, the upload will be dissallowed. If the match is followed by a comment (';' character), the comment will display, otherwise Magnum will generate a message to the user. An example BADUPLD.LST file might look like the following: *.EXE ; Please 'ARC' or 'ZIP' all uploads! *.COM *.LZH PMDIARY?.* ; IBM internal pgm - not public! PM-DIARY.* ; IBM internal pgm - not public! CMD.EXE ; License required to distribute! NOANSCHK.LST - Magnum checks your SESSION DIRectory for a file by the name of NOANSCHK.LST (which you optionally create with your text editor). If it finds it, it checks the file for filename extensions NOT to check for harmful ANSI escape sequences after a file upload. The file contents of of NOANSCHK.LST may look similar to the following: ARC ZIP LZH ZOO GIF BMP Bascially, the contents of the file are the extensions of filenames NOT to run an ANSI escape sequence check on. Because many compressed files (such as ARC and ZIP) can inadvertantly reproduce a harmful ANSI escape sequence to redefine a keyboard key when typed to the screen, it is almost meaningless to check a compressed file because once uncompressed into its individual members, this may not be the case. It's okay to check files with extensions of EXE and COM because they may contain embedded sequences, however, binary files can also inadvertantly reproduce one of these sequences. ANSI checking is mainly helpful for files containing text. The program which performs this checking is CHKANSI.EXE which is located in your EXTernal DIRectory. The format of the NOANSCHK.LST file is one entry per line of file extensions only (do not supply complete filenames or wildcards) - only the extension is checked for a match. COMPRESS.LST - Magnum checks your SESSION DIRectory for a file by the name of COMPRESS.LST (which you optionally create with your text editor). If it finds it, it incorporates the instructions within into the BBS. With COMPRESS.LST, you can support whatever file compression schemes you wish. You can support other file compression formats such as .LZH or .ZOO for example. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-6 Back to Display Files & Subdirectories The SESSION DIRECTORY To support other file formats, create a file called COMPRESS.LST in your SESSION DIRectory with your favorite text editor. The format of this ASCII file is as follows (via example): Definitions for various file compressions. Sample COMPRESS.LST file. Anything not starting with: . C= D= L= T= K= will be treated as a comment line (ignored). .ZIP: C=PKZIP2.EXE -u %s D=PKUNZIP2.EXE -o %s L=PKUNZIP2.EXE -v %s T=PKUNZIP2.EXE -t %s K=PKZIP2.EXE -zq %s .ARC: C=ARC2.EXE u %s D=ARC2.EXE x %s L=ARC2.EXE l %s T=ARC2.EXE t %s .ZOO: C=ZOO.EXE a %s D=ZOO.EXE x %s L=ZOO.EXE l %s .LZH: C=LH.EXE A %s D=LH.EXE X %s L=LH.EXE L %s T=LH.EXE T %s Note that the first nonspace character must begin with . (the period character), or C= or D= or L= or T= or K= in order for it to be a valid statement, otherwise the entire text line is ignored (treated as a comment line). The . character defines the file extension for that particular file compression method. Therefore, .LZH: for example, defines the external programs necessary to process files ending with extensions of .LZH (don't forget to end the extension with the : character). Following .LZH: (for example), are four statements. The first statement, beginning with the C= keyword, defines the program name and parameters for COMPRESSING a file. The %s needed in all definitions represents the file name of the .LZH file and will be substituted with the .LZH file name internally when Magnum processes the file. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-7 The SESSION DIRECTORY Similar definitions exist for the D= keyword (DECOMPRESS), L= (LIST Members), T= (TEST integrity), and K= (Add Comment). Note that in the above example, there is no T= statement for .ZOO file processing. Not that it doesn't exist, but the ZOO processing program we tested didn't have this capability. It's ok to leave out the T= keyword (or any other, but we haven't tested with any keywords left out other than T). Now then, the external compression/decompression program(s) must conform to the following specifications: - Must write their output to STDOUT when listing members of a compressed file. - Must reside in your EXTERNAL DIRectory (do not supply path names in the COMPRESS.LST file). - The %s parameter which represents the file Magnum will be working with, can appear anywhere on the parameter line to accomodate external programs requiring the file name to appear before (as opposed to after) any arguments. - If the external program supports HPFS long filenames, then your WORK DIRectories should all reside on an HPFS drive. Please note that Magnum itself does NOT support long filenames - this lack of support is currently necessary to accomodate FAT systems. Support for long filenames may appear in a future release. - If the external program supports adding a comment (K=) to the file, it must be able read this information from STDIN (Magnum will redirect this information from ZIPCMT.n, where n is node#). Note that in our example COMPRESS.LST file above, we provided definitions for .ARC and .ZIP formats. These definitions are optional because these formats are already built in. However, we provided these definitions to show you how you can override the built-in definitions for .ARC and .ZIP format. If you leave out a X= keyword (ie: C=, D=, L=, K=, T=) then Magnum will use its built-in definition. You may define up to 10 different file compression formats. In our example above, we've defined 4. We could have left out .ZIP and .ARC, which still results in Magnum understanding 4 formats since .ARC and .ZIP are built in unless overridden in this file. In the above example, Magnum will recognize that files ending with .ARC, .ZIP, .LZH and .ZOO are compressed files. You can [A]ccess these files (from file menu) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-8 Back to Display Files & Subdirectories The SESSION DIRECTORY without even providing a file extension. If you upload a file TEST.LZH and Magnum finds a file by the name of TEST.ZIP (or TEST.ZOO or TEST.ARC), it will disallow the upload. It will allow TEST.DOC however because .DOC is not defined as a compressed file format. Please note that the support for any external file compression or decompression programs is completely optional, as is the existence of the COMPRESS.LST file itself. USER.KEY - This file is the USER database KEY file for the BBS. This file will not exist until your first logon. USER.DAT - This file is the USER database for the BBS. This file will not exist until your first logon. FILE.DAT - This file is the FILE database for the BBS. This file will not exist until files are added or uploaded to the BBS. MSG.DAT - This file is the MESSAGE database containing message header information. This file will not exist until messages are entered via the BBS. RJE.DAT - This file is the RJE database containing RJE record information on who ran what jobs when, status of jobs, etc. This file will not exist until your first logon. UTILIZ.DAT - The utilization database (optional) - refer to the TRACK_UTILIZATION keyword in your STARTUP.x file(s). MILC.SUB - Magnum now looks for the existence of a new file (optional) by the name of MILC.SUB in your SESSION DIRectory. If found, it is used to signal Magnum to substitute a specific character with another if found in a @Zx variable. For example, the MILC.SUB's file contents might look like the following: substitute ~ with " 126=34 substitute | with ^ 124=94 The way it works is a statement such as x=y is interpreted as "replace all characters with ASCII decimal value x with ASCII decimal value y". All lines starting with a non-digit are ignored (treated as a comment). In the above example, 126 is the ASCII decimal value for the tilde (~) character. 34 is the ASCII decimal value for the double quote (") character. The statement 126=34 tells Magnum to replace any occurrence of the tilde (~) character found in any @Zx string withe the double quote MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-9 The SESSION DIRECTORY (") character. Thus, the statement: @Z1="this is a ~test~ string"; would be stored (or printed) as: this is a "test" string These automatic, nonreversible substitutions take place only when a @Zx MILC statement is referenced. Although this capability is powerful yet obscure, it does provide an easy way of performing certain things not possible before. For example, if you wanted to have double quotes within a string to pass as a command line argument to a program, this capability provides it. Before this capability existed there was no way to accomplish this task. QSECx.BBS - This file is a quick way of sending a message to a QSECx.SCR certain security level. When a user's security level matches x, the file will be displayed to that user after logon. The file will be sent to matching security levels only once. The next time they log on, the file will not be displayed. To send the contents of the file to all level 100 users for example, simply name the file QSEC100.BBS. ALL QSECx FILES ARE OPTIONAL!! SECx.BBS - Identical to QSECx.BBS but will display EVERY TIME a user SECx.SCR logs on who's security level matches x. ALL SECx FILES ARE OPTIONAL!! IDx.BBS - Similar to QSECx.BBS but x must match the user's ID (not IDx.SCR security level). For example, to send the file to the user who's ID matches 144, name the file ID144.BBS. Once the file is displayed to that user, the file will be deleted. ALL IDx FILES ARE OPTIONAL!! BRDCAST.ALL - For broadcasting a message to all or certain nodes having BRDCAST.n users currently logged on. These optional files can be generated by you or an application program. Refer to chapter 2 (SES_DIR, BRDCAST.ALL and BRDCAST.n) for details on the use of these optional files. PREBADV.BBS - If your STARTUP file has a non-zero number in either the POSTBADV.BBS VERIFY_DOB or VERIFY_PHONE fields, the behavior of Magnum was to force the user into the message editor to explain why a mismatch occurred. Once the message was entered and saved, the user was allowed to continue with their session. Starting with this release, the following is performed instead: 1) Check for and display PREBADV.BBS (in SESSION DIR) if MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-10 Back to Display Files & Subdirectories The SESSION DIRECTORY it exists 2) Force message entry explaining why a mismatch occured 3) Check for and display POSTBADV.BBS (in SESSION DIR) if it exists This new method allows Magnum to function as it always has if you do nothing. If you have a PREBADV.BBS file, you can display a message and implement MILC commands to log the user off! If you have a POSTBADV.BBS file, you can display a message and implement MILC commands to log the user off after forced message entry. Typically, you'd use one or the other file depending on whether you want them to enter a message or not, but you could also use both files if desired. The names of these files are short for "pre-bad-verify" and "post-bad-verify". NOTE: If you're going to implement the use of these files, we highly recommend the first four characters of the file to be @C10 to insure that the user is unable to stop display of the file with their spacebar or <ctrl-x> keys. The @C17 command would actually end the session, so be sure to include this command if this is your intention. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-11 The BULLETIN DIRECTORY Within the BULLETIN DIRECTORY, the following files should be found: BULLETIN.BBS - This is the file which is displayed by MAGNUM when a user BULLETIN.SCR chooses to view the BULLETIN file. This file usually uses MILC commands to act as a menu to include other files or to branch to other areas of this file. Users are notified if the date and/or time of this file has changed since they're last logon. NEWSLTR.BBS - This is the file which is displayed by MAGNUM when a user NEWSLTR.SCR chooses to view the NEWSLETTER file. As with any other display file, it may contain MILC commands to form a menu QUESTION.BBS - This is the file which is displayed by MAGNUM when a user QUESTION.SCR chooses to view the QUESTIONAIRRE file. This file usually uses MILC commands to act as a menu, perform I/O and log user's answers to disk. A typical use might be for an online order system in which users place orders with their credit cards. QUESNEW.BBS - If you've configured MAGNUM such that the GET_QUESTION QUESNEW.SCR parm is Y, then the contents of this file is displayed. This file will typically have MILC commands which will perform I/O and log the user's answers to disk. This file will be presented only once to every user who calls for the first time. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-12 Back to Display Files & Subdirectories The MENU DIRECTORY Within the MENU DIRECTORY, the following files should be found. However, ALL FILES in this directory are OPTIONAL. IF NOT FOUND, MAGNUM builds it's own menus dynamically and displays that instead. MAINMENU.BBS - Create your own MAIN menu in this file. If the file MAINMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. FILEMENU.BBS - Create your own FILE menu in this file. If the file FILEMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. MSGMENU.BBS - Create your own MESSAGE menu in this file. If the file MSGMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. SYSMENU.BBS - Create your own SYSOP menu in this file. If the file SYSMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. RJEMENU.BBS - Create your own RJE menu in this file. If the file RJEMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. NOTE: With the use of imbedded MILC commands, you can effectively create one menu file per section which will look different to every security level. You can even have it appear differently for a particular user! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-13 The HELP DIRECTORY Within the HELP DIRECTORY, the following files should be found. However, ALL FILES in this directory are OPTIONAL. IF NOT FOUND, MAGNUM simply sends the user the "Help not available" message. MAINHELP.BBS - This is the file which is displayed when a user chooses MAINHELP.SCR the HELP option for the MAIN menu. FILEHELP.BBS - This is the file which is displayed when a user chooses FILEHELP.SCR the HELP option for the FILE menu. MSGHELP.BBS - This is the file which is displayed when a user chooses MSGHELP.SCR the HELP option for the MESSAGE menu. SYSHELP.BBS - This is the file which is displayed when a user chooses SYSHELP.SCR the HELP option for the SYSOP menu. RJEHELP.BBS - This is the file which is displayed when a user chooses RJEHELP.SCR the HELP option for the RJE menu. NOTE: With the use of imbedded MILC commands, you can effectively create one HELP file per section which will look different to every security level. You can even have it appear differently for a particular user! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-14 Back to Display Files & Subdirectories The DISPLAY DIRECTORY Within the DISPLAY DIRECTORY, the following files should be found. However, ALL FILES in this directory are OPTIONAL. IF NOT FOUND, MAGNUM simply sends an error message to the console (if you are snooping on the session) - otherwise, the remote USER is not aware of anything different. Any error messages you see as a "snooping sysop" are to be taken as warnings only - the remote user never sees these warning messages. NOTE THAT ALL FILES LISTED BELOW CAN EXIST IN EITHER .BBS or .SCR FORMAT (or both). THE ONLY EXCEPTIONS TO THIS ARE: PRELOG.BBS, LOWBAUD.BBS, CLOSED.BBS, QUOTES.BBS and OPEN.BBS DO NOT CREATE ANY .SCR FILES FOR THE ABOVE 5 FILES!! HELLO1.BBS - Displayed after the user successfully logs on. HELLO2.BBS - Displayed after HELLO1.BBS HELLO3.BBS - Displayed after HELLO2.BBS NEWUSER.BBS - Displayed after logon IF this is the user's FIRST logon. BIRTHDAY.BBS - If you've configured MAGNUM to ask new users for their birth dates, MAGNUM compares their birthdate with the current date. If it matches, the contents of this file is displayed. GOODBYE.BBS - Displayed when the user logs off. PRELOG.BBS - Displays BEFORE the LOGIN: prompt. LOWBAUD.BBS - Displays if the user's baud rate is LOWER than the lowest acceptable baud rate you've defined in the STARTUP.x file CLOSED.BBS - Displays IF you're running a CLOSED BBS and the new user's name is not found in the USER database. OPEN.BBS - Displays IF you're running an OPEN BBS and the user's user's name is not found in the USER database. This is an ideal place to place present the user with some information about the BBS and ask them if they wish to continue to log on as a new user. You can terminate their session with MILC command @C17 if they do not wish to continue. QUOTES.BBS - Displays at logoff. The quote sent is equal to the number of times the caller has called modulus the number of quotes in the file. The file should have the folloing format: %50 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-15 The DISPLAY DIRECTORY %1 This is Quote #1 %2 This is Quote #2. Any quote can use as many lines as you want. %3 This is Quote #3. . . . %50 This is Quote #50. The way this file works is as follows: The very first line in the file is a %x where x is the number of quotes in the file. After that, every quote is numbered with %x where x ranges from 1 to x. There should be NO SPACES between the % character and the quote# (x). The % character should appear in column 1. 50 is the limit used in this example - your actual file can contain as many quotes as you wish. PREUP.BBS - Displayed prior to the user performing an upload. POSTUP.BBS - Displayed after the user performs an upload. PREDOWN.BBS - Displayed prior to the user performing a download. POSTDOWN.BBS - Displayed after the user performs a download. UDRATIO.BBS - Displayed when the user's upload/download ratio has been exceeded. PRELIST.BBS - Displayed prior to performing a LIST FILEs command. NEWMSG.BBS - Displays when a user chooses "[E]nter New Message". This file is an ideal place to put some brief information as to what ID to write to for "Tech Support", "Marketing Information", etc. FILESRCH.BBS - Displays (if exists) in lieu of the built-in text when the "[T]ext Search" function of the file menu is chosen. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-16 Back to Display Files & Subdirectories The EXTERNAL DIRECTORY The following are the files (programs, text, .cmd files, etc) which are called/displayed by MAGNUM: CMD.EXE - As long as this file (included with OS/2) is in your PATH statement (CONFIG.SYS file), it does NOT have to be placed here! ARC2.EXE - Called when the user wishes to create/view a .ARC file. NOTE: NOT INCLUDED WITH THE BBS PACKAGE BUT AVAILABLE FOR DOWNLOAD FROM GILMORE SYSTEM'S BBS. PKZIP2.EXE - Called when the user wishes to create a .ZIP file. PKUNZIP2.EXE - Called when the user wishes to view a .ZIP file. UNZIP16.EXE - This program should be downloaded from our BBS and renamed to PKUNZIP2.EXE (as of this writing, PK-Ware has NOT released an OS/2-equivalent of the v2.04G format of their ZIP utils --- UNZIP16.EXE is a 'clone' which DOES understand the 2.04G ZIP format). ZIPCMT.x - A text file (x=node number) which, if exists, gets placed into any uploaded .ZIP file as a "ZIP file comment". Useful for advertising your BBS, etc. Requires PKZIP2.EXE CHKANSI.EXE - Called after every upload, and after every message entered. Checks if the uploaded file or new message has any harmful ANSI escape sequences imbedded within which may redefine your (or another user's) keyboard when viewed. If harmful escape sequences are found, MAGNUM automatically locks the user out of the system and logs them off! Included with the package. CHILDREN.BBS - Menu for external programs (known as 'doors' on DOS CHILDREN.SCR BBS's). The way this works is that upon exit of displaying this file, the variable @Z0 should hold the program name (no path or drive, just program name), variable @Z1 should hold command line arguments to be passed to the child (if any), and @N0 should hold either 0 or 1 where 0=child handles local echo, 1=door handles local echo. Subject to change. See our example CHILDREN.BBS file (included). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-17 The RJE DIRECTORY When the [L]ist/Execut option of the RJE menu is chosen, the file RJELIST.BBS (or RJELIST.SCR) is displayed - this file is expected to be found in the RJE DIRECTORY. Any program started from this file, or any other display file (with the @E1 command), will be expected to be found in this subdirectory. Output files created by your RJE programs are usually ARC'd or ZIP'd and placed in the RJE RESULTS AREA (one of your file download areas) for download (placed there with ADDRJE.EXE). File naming convention used is Ux@y.ZIP - where x is the user's ID number, and y ranges from 0 to F (hex) - if there are already 16 files to the user's name, no more will be allowed. All files in this section are automatically private with the user's logon password (if the user's logon password exceeds 10 characters, only the first 10 characters are used as the password). Files created by the [M]ake selection of the [F]iles menu are set to expire the following day, or will be deleted as soon as the user successfully downloads it. If you'll be writing your own programs to run as RJE jobs, run ADDRJE.EXE without parms for instructions on its use. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-18 Back to Display Files & Subdirectories The MESSAGE SUBDIRECTORY Where message files go. Any messages which are a description of an available file for download, will have the same filename as the downloadable file. MSG DIRECTORY is the parent subdirectory, and there MUST be 26 subdirectory entries within this directory, named A to Z. (IE: \magnum\msg\a, \magnum\msg\b ... \magnum\msg\z). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-19 The WORK SUBDIRECTORY Temporary workspace to hold extracted members of .ARC or .ZIP files and other temporary workspace needs. IMPORTANT: The WORK directory MUST BE UNIQUE for each node!!! We recommend d:\MAGNUM\WORK_DIR\1, d:\MAGNUM\WORK_DIR\2, etc (where d: is the drive Magnum is installed on... make sure these directories exist!). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 6-20 Back to Display Files & Subdirectories The SYSOUT SUBDIRECTORY ACTIVITY.x - These files (x=1 for node 1, x=2 for node 2, etc) will be created if they don't exist. They contain a summary of activity on the board for the node they represent. These ACTIVITY.x files can grow very large in a short period of time. Therefore, it's a good idea to periodically delete these ACTIVITY.x files from time to time in order to conserve available disk space. SYSCHAT.LOG - This file will be created the first time you SYSCHAT with someone (not to be confused with GROUP chat). It will be appended to with all subsequent SYSCHAT's. You may delete this file anytime it gets too large. This file holds the contents of your "chat" sessions. GRPCHAT.LOG - This file will be created the first time 2 users speak with each other via the Group Chat option. It will be appended to with all subsequent Group Chat's. You may delete this file anytime it gets too large but you must terminate MBBS first. This file holds the contents of all Group Chat's. *.R?? - Any questionairres you may have - anytime I/O is used to write to disk with the @Z or @N commands, the responses go to the same filename as what they're responding to, only with an extension of .R?? where ?? is the node number the user is on when they're responding to the file. For example, if a user on node 2 is responding to questions within the file QUESTION.BBS, the results will be placed in QUESTION.R02. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Back to Display Files & Subdirectories Page 6-21 The USER SUBDIRECTORY The USER subdirectory holds files specific to your users. For example, if you allow any of your users access to MILC commands @Zx or @Nx, they have the ability to create messages which can ask questions of the reader and log their answers to a file. Those 'answers' get logged to a file in the USER DIRectory under the same name as the message file. User NotePads are also kept in this subdirectory. Any user who's created one or more notes will have files in this subdirectory. The NotePad files have the following naming convention: IDxxxxx.NPT - NotePad Titles for User ID xxxxx IDxxxxx.Nnn - NotePad nn for User ID xxxxx (nn = 00 to 99) This is for your own information. The remote user is oblivious to Magnum's directory structure or file naming conventions. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank Using Magnum BBS as a USER Page 7-1 As a USER, either remote via modem, or local via the console, Magnum BBS software is fairly simple and self explanatory. All menus offer online help which you can display by choosing the [?] command. A help file will be displayed which you've created (or altered from the file we supply). We have not supplied a help file for the Sysop menu, but feel free to create your own. A few 'not-so-obvious' usages of the system are command chaining. Whether or not a user is using single-keystroke commands (hotkeys), command chaining (also known as command stacking on some systems) is available at ANY prompt. To use command chaining, simply begin your entry with the semicolon (;) character. For example, if you are in the Main Menu and wish to read all mail since the last logon, you would enter: ;M;R;S Not only does this save time but omits displaying the actual menus when commands are chained. Unlike other systems, command chaining MUST START WITH THE SEMICOLON (;) CHARACTER!! Another not-so-commonly-known trick is to stop the display of any text file simply by hitting the <Ctrl-X> key combination). This way a user is not forced to read through a file in its entirety if they do not want to. There is a command (see MILC) which you can imbed in the file to disable the ability to stop its display with <Ctrl-X>. One more shortcut you can use on the system is the entry of dates when responding to any date prompt. For example, regardless of whether your date setting is European or US date format, you can enter a date in either format (MM/DD/YYYY or DD.MM.YYYY). Your default dateformat setting is used by Magnum only for display purposes. Also, you needn't enter a 2-digit month, or a 2-digit day, or a 4-digit year. As a matter of fact, the year is optional! Magnum will assume the following about dates: If a month or day is entered as 1-digit, it will internally convert it to 2-digits (by adding a leading 0). If the year is omitted, the current year is assumed. If a 1-digit year is entered, the current decade is assumed. If a 2-digit year is entered, the current century is assumed. If a 3-digit year is entered, the current millenium is assumed. If a 4-digit year is entered, that year will be used. By way of example, the following are all valid ways of entering June 5, 1991 (assuming the current year is 1991): 06/05/1991 or 05.06.1991 06/05/991 05.06.991 06/05/91 05.06.91 06/05/1 05.06.1 06/05 05.06 06/5 5.06 6/05 05.6 6/5 5.6 6/5/1 5.6.1 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-2 Using Magnum BBS as a USER There are other combinations to represent the same date, however the above should provide a sufficient example. If the current year were 1991, and you wish to express June 5, 1990, you could enter 6/5/0 or 5.6.0 or 6/5/90 or 5.6.90. Magnum BBS will automatically inform users if new mail has arrived for them during the course of their online session if the mail is NEW as of this session (checked every 60 seconds). When in the [F]iles menu, users tend to look for a file such as ALLFILES.ARC or similar name. What they're really looking for is a compressed file (ARC or ZIP) which contains a list of all the available downloadable files on the BBS. Traditionally, most BBS systems offer this file, which is updated once per day. With Magnum, however, the user simply chooses the [M]ake selection - Magnum will "make" an ARC or ZIP file containing a list of all available files on the BBS according to the user's selection criteria. The user is guaranteed that the created 'filelist' will be accurate as of the moment it was created. The user has until midnight that night to download the file - it will be automatically marked for deletion after midnight and will no longer be available for download. The created filename is of the format Uxxxxx@y.ARC or Uxxxxx@y.ZIP depending on whether ARC or ZIP is the default compression type in the user's profile. The 'xxxxx' part of the filename is the user's ID number, and 'y' is the number of downloadable files the user created today. 'xxxxx' can be from 1 to 5 digits, and 'y' can be a hex number from 0 to F. In other words, a filename of U12@0.ARC is read as "User /12 filenumber 0". U5@B.ZIP is read as "User /5 filenumber 11". Files of this type are automatically placed in the RJE subdirectory and are password protected with the user's logon password. Make sure you allow your users download capability from the RJE directory. The LOGIN prompt (ie: Enter First Name or /ID# => ) can accept any of the following responses: /ID# ( ie: /10 ) FirstName FirstName LastName FirstName MiddleInitial LastName FirstName MiddleName LastName The LOGIN function is intelligent enough to find a user whether or not they use their middle name, or whether or not they supply a middle initial as opposed to a middle name. The LOGIN prompt accepts up to 20 characters of input... if the full name (firstname and lastname as a minimum) will fit within this space, it will be accepted. If it exceeds this space, supply firstname followed by ENTER, then optional middle name followed by ENTER, then last name followed by ENTER. In the event of duplicate first and last names, the middle initial or middle name will be used to clarify further (ie: JOHN D SMITH, JOHN S SMITH, etc). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-3 Handles (Alias Names) If you allow handles on your system [ALLOW_HANDLES: Y -- in your STARTUP files(s)], your users must still log onto the system using either their real name or their ID number. Once on, everyone else will know the user by their handle (and ID number). Any/all messages entered by a user will bear their handle within the message headers (ie: FROM and/or TO fields), the user search function, who's on, and all other BBS functions which display a user's name will display their handle instead (except for the Sysop and CoSysop, message headers will show the Sysop and CoSysop both the handle and real name). Users need not use handles, they may choose to use or not use a handle at first logon or (if permitted) via the main menu's "[E]nvironment" option #4. If you'll be writing any kind of programs (including Magnum's .mex programs), keep in mind that the street1 field will hold either the user's handle or company name (check the boolean use_handle field to find out which). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-4 Using Magnum BBS as a USER The MAIN MENU The MAIN MENU, like any other menu in the system is SYSOP configurable. The SYSOP can choose to have the menu appear however they want, whether it's built dynamically by Magnum (via your STARTUP definitions) or whether it's an externally displayed file. Therefore, we will use the definitions for the MAIN MENU (and all menu's for that matter) supplied in our supplied STARTUP files for the purposes of documentation. The MAIN MENU, as with any other menu on the system will appear differently for different users depending on their security level. For example, you, as SYSOP, should have the highest security level on the system... the [X] option in the main menu (Sysop use only) should be defined in your STARTUP files as being available to security levels matching your security level as SYSOP. Therefore, users with lower security levels will not even see the [X] option in the main menu. Likewise, users with matching or greater levels than those defined by the individual menu selections will see those selections only and not those requiring higher security levels. The MAIN MENU currently has 19 different menu selections. We'll present these menu options one at a time: MAINMENU_MSG: (menu selection M) This menu selection takes the user into the "Message Section" of the BBS where s/he will be presented with the Message Menu (see MESSAGE MENU later in this chapter). MAINMENU_FILE: (menu selection F) This menu selection takes the user into the "Files Section" of the BBS where s/he will be presented with the Files Menu (see FILES MENU later in this chapter). MAINMENU_RJE: (menu selection R) This selection takes the user into the "RJE Section" of the BBS where s/he will be presented with the RJE Menu (see RJE MENU later in this chapter). MAINMENU_BULLETIN: (menu selection B) This menu selection presents the user with the BULLETIN.BBS file (expected to be found in the BULLETIN directory) which you've created (or will create) with your text editor. See MILC commands in an earlier chapter for how to create menuing systems. Because BULLETIN.BBS is reported to a user as being changed if it's been modified since that last time the user viewed the BULLETIN.BBS file, it is important that anytime you change any of the "included" files brought up by this file (if any), that you change the date of this file as well - otherwise, the user will not be notified of an update to bulletins. What we do at Gilmore Systems, is to present the user with a choice of bulletins to read via the BULLETIN.BBS file, and next to each choice we have the date MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-5 The MAIN MENU of last modification enclosed in parenthesis. MAINMENU_QUESTION: (menu selection Q) This menu selection presents the user with the QUESTION.BBS file (expected to be be found in the BULLETIN directory) which you've created (or will create) with your text editor. See MILC commands in an earlier chapter for how to create menuing systems. MAINMENU_COMMENT: (menu selection C) This menu selection allows the user to enter the line editor or the ANSI message editor in order to leave a private message to the sysop. Once the user answers the prompt of which editor they wish to use, they can then enter a Comment (message) which will automatically be addressed to the Sysop (ID: /0) and marked as private (regardless of whether private messages are allowed or not). Unlike entering a message to the sysop from the MESSAGE section, the COMMENT selection from the main menu does not prompt the user for any header information - the user is taken directly to the selected editor for message entry. If using the line editor, enter the word "/EXIT" (without quotes) on a line by itself. The main menu's [E]nvironment option also lets a user change their profile such that they can end message entry with a null line (two successive ENTER's). Up to 150 text lines are allowed for any message entry, however, if your system is running quite low on memory, it will inform the user of the maximum number of text lines it is able to use. By the way, "/EXIT" can be shortened to "/EXI" or "/EX" (all without quotes of course), and is case independent. MAINMENU_PAGESYS: (menu selection Y) This menu selection first checks to see whether the current time of day coincides with the Sysop's paging hours. If it does, AND the Sysop's BELL parameter is on (see Sysop console commands), then Magnum will audibly page the Sysop for 30 seconds. The user can terminate this paging earlier by pressing <Ctrl-X> at their terminal. If the Sysop wishes to "chat" with the user doing the paging, the sysop can switch to the user's session and press <F7>. If the Sysop has not pressed <F7> before the 30 second paging is over, the user is presented a message stating "Sysop not responding to page...". In the event the current time of day does not coincide with the Sysop's paging hours, the user is notified of the Sysop's paging hours. MAINMENU_WHO: (menu selection W) This menu selection will present the user with a list of users (by ID#) of all who are on the system, regardless of which computer (in a LAN environment) they're logged on from. See WHOS.ON in chapter 2 for additional information. MAINMENU_CHAT: (menu selection S) This menu selection allows the user to enter GROUP CHAT mode. Many MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-6 Using Magnum BBS as a USER The MAIN MENU Sysops disable this feature (assign a security level higher than any user to this function) because of abuse potential (fowl language, etc), but many Sysops also enjoy having the feature enabled. As a Sysop, this is your prerogative. When a user chooses this menu selection, they will be placed in GROUP CHAT mode and can page others on the system and send them immediate one-line private messages. If two or more people enter GROUP CHAT mode, they can converse with each other simply by typing back and forth. While a user is typing, Magnum is collecting what they type - when they reach the end of a text line, automatic wordwrap will work the same was it does as if they were typing a message in the message section. Each time automatic wordwrap happens, the line that the user just finished typing (prior to automatic wordwrap) will be sent to all nodes. This process repeats until the user presses their ENTER key. The ENTER key merely sends the current line. The user can also enter commands while in GROUP CHAT mode. A command starts with the / (forward slash) character in column one. The following commands are supported: /HELP - presents the user with this list /EXIT - End chat. Return to BBS. /MSG x "message text" - Send private msg to node x. /NODE x - Page user on Node x. /PAGEON - Allows you to be paged by others. /PAGEOFF - Turns your pager off. /TIME - Shows current time and time remaining. /WHO - Identical to MAINMENU_WHO above. As with all commands on a Magnum system, case is unimportant - uppercase, lowercase, or any combination of each are all the same to Magnum. As is the case for ending Message entry, ending GROUP CHAT can be accomplished by entering one of /EXIT, /EXI or /EX on a line by itself. MAINMENU_INITIAL: (menu selection I) Selection of this menu item redisplays the initial welcome screen by displaying the files HELLO1.BBS (or HELLO1.SCR) thru HELLO3.BBS (or HELLO3.SCR). If you have colorful ANSI graphics in these screens or some special announcements, some users may want to have another look at it and this menu selection enables them to do so without them having to call back just to see those screens again. MAINMENU_USERS: (menu selection U) This menu selection provides the user with a means of listing the users in your USER database. When a user chooses this menu selection, a prompt will be accompanied by an explanation of the various ways a search can be performed. For example, if the user enters the * character in response to the prompt, ALL users in the USER database will be displayed including the dates of their last call to the system. If the user enters one or more characters of a user's last name, a list of all users who's first one or more letters of their last name matching the entry will be displayed. If a user wanted to search by company name, they'd start with the \ character - for example, to search for MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-7 The MAIN MENU those from IBM, they'd enter \IBM - this would result in matches for IBM, IBM Corp, etc. Note that the search will match the letters entered if it finds it ANYWHERE within a company name. Lastly, a user can cross-reference other users according to user interests. If a user wanted to search for others who's interests were OS/2 and/or MUSIC, they would enter ?OS/2 MUSIC in response to the search criteria. This would result in a match for all users with an interest in OS/2 or MUSIC. NOTE: If the GEO_PRIVACY parm in your STARTUP.x file(s) is set to 'Y', then geographic information about any users will be omitted. MAINMENU_PARMS: (menu selection E) This menu selection allows a user to change the parameters in their profile. Currently, 27 changeable parameters exist. A typical display may look something like the following: 1) Default System Compression Type: ZIP 2) End Message Entry with null line (line editor only): NO 3) Your "page" switch is: ON 4) Company: XYZ Corporation 5) Street2: 123 Anystreet 6) City: Anytown 7) State or Province: CA 8) Zip: 90067 9) Country: USA 10) Password (non shown for security purposes): ****** 11) BirthDate: 06/01/1955 12) Phone1: 213-555-1234 13) Phone2: 213-555-4321 14) Computer: IBM PS/2 model 80 15) Default File Xfer Protocol: None 16) ANSI color: yes 17) Display "More" prompt: yes 18) Erase "More" prompt: yes 19) Use Single Keystroke Commands (no C/R required): yes 20) Your areas of personal interest: : OS/2 PM COMMUNICATIONS 21) Lines per screen: 23 22) Date Format (US, Europe): U Enter # to change (1- ), 0=display static info, N=Next page, Q=quit => A user can change any of the above parameters by entering it's number. For example, to change ANSI color from yes to no, the user would enter 16. When prompted for ANSI color, the user would supply N (no). Note that selection 4 doubles as Company name or Handle (alias) depending on system and user criteria for this option. Note that any of the above parameters can be dissallowed for changing: refer refer to NOCHANGE.LST in the SESSION DIR portion of Chapter 6. If the user wanted to see their permanent info, they could enter 0 at this point amd a display similar to the following would appear: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-8 Using Magnum BBS as a USER The MAIN MENU User ID: "/10" Security Level: 20 First called on (mm/dd/yyyy): 12/27/1989 Last called on (mm/dd/yyyy): 01/07/1990 Last new files search (mm/dd/yyyy): 01/01/1980 File xfer CPS rate: 240 Download limit per week: 700 files or 70000 K-bytes Conferences available to you: ABCEFGH Number of times you called: 12 Minutes of connect time remaining for the week: 105 minutes Note that if a user chooses European date formats, all dates will be in the format DD.MM.YYYY and all prompts requiring a date will also expect the input to be in this format. US date formats are in the form of MM/DD/YYYY. If the user chooses N (for NEXT page), a display similar to the following will display: 23) Nulls to send after CR: 0 24) "List Files" preference: None 25) "Editor" preference: None 26) Show Extended (long) File Descriptions during Listings: Y 27) Internet E-mail address: id10@gilmore.com Enter # to change (23- ), 0=display static info, P=prev page, Q=quit => MAINMENU_STATS: (menu selection V) This menu selection displays system statistics. A typical display might look like the following: MAGNUM BBS (r) (C)Copyright 1989 Gilmore Systems: Serial # 1989070000 Parent (System) Serial#: 1989070000 Magnum Version 5.00C4 OS/2 Version: 1.30 BBS Name: "Gilmore Systems Home of MAGNUM OS/2 BBS" BBS Started: July 14, 1989 Total calls this node (node 1): 11241 Sysop: Chuck B Gilmore Sysop Paging Hours: 00:00 to 23:59 BBS settings: Parity=N, Databits=8, Stopbits=1 Modem: USRobotics Dual Std DTE Initial: 19200 (locked) User Records: 2250 Message Records: 2015 File Records: 1022 RJE Records: 115 Last system restart: 10/17/1990 16:27:07.06 As you can see, the list describes the Sysop's modem and DTE rate, number of records in the databases, number of callers for the particular node, paging hours, etc. This enables users to get a summary of your MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-9 The MAIN MENU BBS at a glance. MAINMENU_CHILD: (menu selection D) This menu option displays the file you created (or will create) with your text editor by the name of CHILDREN.BBS - the file is expected to be found in your EXTERNAL directory. See MILC commands for creating menuing systems. See CHILDREN.BBS in Chapter 2 for a description of how to communicate to Magnum which program to run and how it is to be run. MAINMENU_NEWS: (menu selection N) The description of this menu selection is identical to the description given for MAINMENU_BULLETIN except that the filename which will be displayed is NEWSLTR.BBS (expected to be found in the BULLETIN directory). MAINMENU_GOODBYE: (menu selection G) This menu selection prompts the user as to whether they really want to end their session or not. If Yes, they are prompted as to whether they wish to leave a Comment to the Sysop prior to disconnecting (See the VERIFY_GOODBYE option in the STARTUP file). MAINMENU_EXPERT: (menu selection T) This menu selection is actually a toggle switch. It simply reverses expert mode. In other words, if the user has full (complete) menus, choosing this selection will put the user in Expert mode (no menus, just a 1-line prompt showing valid menu characters). If the user is already in Expert mode, choosing this menu selection will put the user back into full-menu mode. MAINMENU_HELP: (menu selection ?) This menu selection will display the MAINHELP.BBS (expected to be found in the HELP directory) if it exists. If this file does not exist, a "help not available" message will be sent to the user. If the file exists, the contents will be displayed to the user. MAINMENU_SYSOP: (menu selection X) This menu selection is usually set to the highest security level so that it is only visible and selectable by the Sysop. Choosing this menu selection allows the user to enter the Sysop Menu. See SYSOP MENU later in this chapter for more information. MAINMENU_OPT1: (menu selection 1) MAINMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file MAINOPT1.BBS or MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-10 Using Magnum BBS as a USER The MAIN MENU MAINOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. MSGMENU_BASEUP: (menu selection +) MSGMENU_BASEDN: (menu selection -) These menu selections are to be used with the optional Extended MsgBase module. These commands are a 'shortcut' for a user to move to the next available MsgBase or next preceding MsgBase s/he has access to. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-11 The MESSAGE MENU The Message Menu currently has 10 selections available: MSGMENU_QUIT: (menu selection Q) This menu selection quits the Message section, returning the user back to the Main menu (see MAIN MENU earlier in this chapter). MSGMENU_UPDT: (menu selection C) This menu selection allows the user to choose which message areas they want to work on. Note that Magnum will only allow users to choose message areas they are authorized to use. By choosing this selection, users can limit the areas such that only areas coinciding with their interests are applied. MSGMENU_READ: (menu selection R) This menu selection enters the "Read Messages Submenu", where the user specifies how and what they wish to read. The "Read Messages Submenu" looks like the following: C = Change Conference Areas B = Backwards Read (newest first) D = Date to start from NOTE: Updates MsgPointers! M = Match Text R = by Reference # S = Since Last Read NOTE: Updates MsgPointers! U = To/From User (or to/from you) V = View MY unread mail + = Change to Next Succeeding MsgBase \__ Appears with Ext'd MsgBase! - = Change to Next Preceding MsgBase / Q = Quit When choosing most of the options, you'll see a "Scanning" message. This message is followed by a dot (.) for every 100 messages scanned. Note that choosing D (or U and supplying a date) will read by posting date (not actual date) in order to preserve outside mail or mail that was posted from other systems. Note that choosing suboptions D or S will update the user's "last read" message references numbers in their user profile. All other selections will have no effect on their "last read". The rest of the submenu is self explanatory. At the end of reading any message (other than a Receipt message generated by Magnum), an internal message disposition submenu is built dynamically and presented to the user. This disposition submenu can have any combination of the following: [A]gain (re-read message) [B]ackThread (Appears when this is a response to a previous MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-12 Using Magnum BBS as a USER The MESSAGE MENU message. Choosing this option will find and display the previous message. You must choose the [N]oMoreThread option to get out of BackThread mode). [C]ontinuous (perform continuous (nonstop) reading of messages. No message disposition submenu appears after messages. Continuous reading is for those who wish to capture all messages to a file. Continuous reading will be stopped if the user presses their <Ctrl-X> key combination). [E]dit (Appears if this message if from you, and it has not been read by the addressee yet. If the message is public, this option only appears if the message has not been read by anyone else. Choosing this option puts the message back into Magnum's line editor and allows you to edit the message). [F]orward (Appears if this message is to you. If you'd like someone else to receive a copy of this message, choosing this option will prompt you for that user's ID). [K]ill (delete message - appears only if message is to/from you, and Sysop allows users to delete messages). [N]ext (read next message) [O]rigin (Appears when this is a response to a previous message. Choosing this option will find the Origin, or original message that started this thread). [P]rivate (Appears if this message is a public message to/from you. Choosing this option changes the message from public to private). [P]ublic (Appears if this message is a private message to/from you. Choosing this option changes the message from private to public). [Q]uit (Quits the "Read Messages Submenu" and returns the user back to the "Message Menu"). [R]eply (enter a reply to this message) [T]hread (Appears when there is a response to this message. Choosing this option will find and display the response. You must choose the [N]oMoreThread option to get out of Thread mode). [V]iew (Appears only if the user viewing this message is the creator of the message. If this user is allowed access to MILC commands -in particular, @Zx and @Nx- where answers can be logged to a file, this option will show the user the answers to those questions). [+/-] (Pressing the '-' key causes Magnum to read messages in reverse chronological order. Pressing the '+' key causes Magnum to read messages in chronological order. This option will not appear when reading 'S'ince, or from 'D'ate options in the "read messages" submenu). Normally, the default choice will be [N]ext. Sometimes it will be [T]hread depending on whether you're reading sequentially or following a thread. In either case, the default choice will be denoted by MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-13 The MESSAGE MENU parenthesis instead of brackets - for example (N)ext instead of [N]ext. When a default choice is indicated on the message disposition submenu, the user need only press their ENTER key to accept the default. NOTE: When [T]hread was previously chosen, and (T)hread is the default, Magnum will stay in this state until [N]oMoreThread is chosen! Note that 'H' is an option available only if logged on locally (Sysop console). It does not show up as an option. The 'H' option, if chosen, will provide a HARDCOPY of the message and will prompt you for the filename or device name of where to print the hardcopy. When performing a hardcopy, note that any embedded MILC commands are printed as is (unprocessed). NOTE: If you're the Sysop or CoSysop (security level of SYSOP_MAIL_LVL or greater), you may press <Ctrl-E> at the message disposition prompt in order to either modify the message text or message header. MSGMENU_SCAN: (menu selection S) In order to choose this option, a user must have chosen a default conference, or a group of default conferences with the MSGMENU_UPDT (menu selection C) option. By choosing this option, only the headers of the messages, but not the actual messages themselves, will be displayed. MSGMENU_ENTER: (menu selection E) This menu selection tells Magnum that the user wishes to enter a message. Magnum will respond to this selection with a series of prompts: Which Conference (? for list) => Who is this message to? (/ID#, ALL, SYSOP, ?=UserList, blank quits) => if the above is to /ID# or SYSOP, it will display: To "JOHN S DOE" (default=Y) (Y/N) => as an example. if the above is to /ID# or SYSOP, and private messages are allowed on your system, the following will display: Is this a Private Messages (default=N) (Y=yes, N=no)(Y/N)=> Subject => Expiration date (MM/DD/YYYY) or blank for None => Do you want a receipt for this message (default=N) (Y/N) => Editor Type: A)nsi, L)ine => After the prompts have been answered, the user will be in the selected editor (line or ANSI) for message entry. The user may now enter their message (or perform an ASCII upload such that no text line exceeds 72 characters). As the user types their message, automatic wordwrap will take place at the end of each text line if necessary. * * * THE FOLLOWING TEXT IS FOR THE ANSI-EDITOR ONLY: * * * ---------------------------------------------- MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-14 Using Magnum BBS as a USER The MESSAGE MENU The ANSI editor is self explanatory - all commands are at the top of the user's screen during message entry on lines 1-9. The user can enter up to 150 lines of message text. The text entry "window" is on lines 10-22 meaning the most current 13 lines of text are visible at any given time. NOTE: If the user changed their lines/page in the main menu's [E]nvironment section to a larger value than 23, Magnum will attempt to accomodate their increased screen length by offering a larger message entry area. A copy of the ANSI-EDITOR message entry screen is as follows: * * ANSI SCREEN CONTROLS IN EFFECT * * | Ctrl-Key Combinations: /\ //\\ | K=End (save) | T=Type Msg Ctrl-W Ctrl-R | Y=Delete Line| X=Play Msg < Ctrl-A Ctrl-D > << Ctrl-Q Ctrl-E >> | G=Delete Char| B=Ins Char Ctrl-Z Ctrl-F | L=Abort Msg | O=Search \/ \\// | V=Insert Line| U=Srch/Repl Hit <ESC><ESC> for options. Max 150 lines| I=TAB | N=Goto Lin# Lines 1-13 ------------------------------------------------------------------------ _ ------------------------------------------------------------------------ The above sample entry screen is self-explanatory. However, a couple of clarifications are warranted. Firstly, the <ESC><ESC> option (meaning to press your <ESC> key twice in succession, will present you with an options menu. This options menu will allow you to view the message header Magnum will be using in your message. If you're responding to a message, you'll be allowed to re-read the message you're responding to, and "quote" text lines from that message to be brought into your message. Automatic wordwrap and page (screen) scroll is in effect when appropriate. Depending on whether you're creating a new message from scratch or responding to another message, other options which may appear in the options menu are 'RePlay Original Message', 'ReRead Original Message with Marking Facilities', and 'NotePad Facilities'. See the chapter entitled "NotePad Facility" for more information on using the NotePad in conjunction with messages. IF YOU'RE LOGGED ON LOCALLY: You can use your Ins, Del, PgUp, PgDn, Home, End and arrow/cursor keys in addition to the <Ctrl-key> MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-15 The MESSAGE MENU combinations defined on top of the message entry screen. The <Ctrl-End> key (available only while online locally) deletes all characters from the current cursor position to the end of the line the cursor is on. * * * THE FOLLOWING TEXT IS FOR THE LINE-EDITOR ONLY: * * * ---------------------------------------------- If using the line editor, message entry is exited by entering one of the following (case independent) on a line by itself starting in column 1: /EXIT /EXI /EX Note that a user could also exit message entry by entering 2 consecutive CR's (press ENTER twice in a row, causing a NUL line) if they went into their [E]nvironment (from Main Menu) and changed #2 to YES. Once a user has exited message entry, another submenu will appear as follows: Edit Commands: [S]ave, [T]ype, [D]elete, [I]nsert, [C]ontinue, [A]bort, [E]dit line, [R]eplace line, [G]o The [S]ave option saves the message and prompts for CC (Carbon Copies) if the message is public and to an individual user. Note that you'll also have a chance to "attach" (by pressing <Ctrl-A>) a file to your message. An "attached" file is really a file that's associated with your message. Anyone having the read rights to your message may download the "attached" file. The "attached" file is usually a binary file (ie: a .ZIP file, although it can be any format) and bears the same name as the actual message itself. The real name of the file is placed in the last line of the actual message in the form of: "If downloading attached file, rename to 'programs.zip'" "Attached" files reside in the MSG_DIR (the parent), not in one of the A, B, C... Z subdirectories of MSG_DIR. If using Magnum's Remote Mail, "attached" files transfer to a remote system along with the message! The [T]ype option simply redisplays what's been entered so far to the user's screen. The [D]elete option allows the user to delete a line or a block of lines. The [I]nsert option allows the user to insert a new line inbetween 2 existing lines. The [C]ontinue option places the user back in message entry mode from the point they left off at (last or highest line# they've entered). The [A]bort option aborts message entry altogether but first prompts the user as to whether an abort is their real intention or not. The [E]dit line option allows a user to change any character(s) or word(s) in a line to any other character(s) or word(s) in a line. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-16 Using Magnum BBS as a USER The MESSAGE MENU The [R]eplace line option allows the user to replace an existing line with new text. The [G]o option allows a user to view their message exactly the way any recipient (reader) of the message would see it - including processing of MILC commands. NOTE: When the [S]ave option is chosen, Magnum runs CHKANSI.EXE (in your EXTERNAL directory) to check the message for harmful ANSI escape sequences. If an ANSI escape sequence is found which can redefine a key on the keyboard (it can do this when someone else remotely reads the message on their keyboard), then Magnum will automatically delete the message, lock the user out of the system, and hang up. This is a built-in security precaution which can be removed by simply deleting (or renaming) the CHKANSI.EXE program in the EXTERNAL directory. In the event of a user lockout, Magnum will create a message to the Sysop about the lockout. MSGMENU_KILL: (menu selection D) This option prompts the user for the Reference # (11 characters) of the message s/he wishes to delete. Magnum then checks to make sure that the message matching this reference # is either to or from the user - if it is, Magnum deletes the message, otherwise the deletion is disallowed. MSGMENU_SRCH: (menu selection T) This option prompts the user for a string of text. Magnum then searches the message database (only areas authorized to the user) for this text string within the SUBJECT descriptions of the messages. Magnum then displays the headers (only) of the messages matching the search. MSGMENU_CHECK: (menu selection P) This option is identical to the "Check Your Mail? (Y/N) => " prompt which appears after a user logs on (just before displaying the main menu). It simply checks the message database for any mail addressed to you which you have not yet read. MSGMENU_GOODBYE: (menu selection G) This menu selection prompts the user as to whether they really want to end their session or not. If Yes, they are prompted as to whether they wish to leave a Comment to the Sysop prior to disconnecting (see the VERIFY_GOODBYE option in the STARTUP file). MSGMENU_HELP: (menu selection ?) This menu selection will display the MSGHELP.BBS (expected to be found in the HELP directory) if it exists. If this file does not exist, a "help not available" message will be sent to the user. If the file exists, the contents will be displayed to the user. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-17 The MESSAGE MENU MSGMENU_OPT1: (menu selection 1) MSGMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file MSGOPT1.BBS or MSGOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. MSGMENU_BASE: (menu selection M) This menu selection is for those who've purchased [and installed] our 'Extended MessageBase' module. If you're not using this module, you should raise the security level of this menu option such that it does not appear on any user's screen. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-18 Using Magnum BBS as a USER The FILES MENU The Files Section of Magnum provides some powerful features. Before we get into the menu definitions, let's start with a brief explanation of some of the unique built-in features. Firstly, Magnum assigns a number (#nnnnn) to every file in your file database(s). This #nnnn is the record number of any particular file in the file listings. At any prompt within the file section which requests a filename, you may provide the #nnnnn instead (start with the # character). The #nnnnn number method is *extremely* fast! Note however, that #nnnnn numbers will change after any time you perform a pack of the file database(s). Magnum's file section also has the ability to 'mark' files for download. When the remote user performs a file listing (and their MORE prompt is set to come on after every screenfull), part of the MORE prompt is the [U]tils selection. By choosing [U]tils, the user can 'mark' the file for download, 'view' the file and members within if it's a compressed file, 'read' the file if an ASCII text file, obtain 'info' on the file, etc, without losing their place in the file listings. When 'D'ownload is finally chosen from the files menu, marked files will automatically be placed on the user's download list (s/he needn't re-enter them), but will be given a chance to view and/or modify the marked files list prior to actually downloading. Note that system-created files such as a compressed file listing will automatically be placed on the user's download list as a 'marked' file. Any user-specific files generated by the system are automatically placed on the user's download list at logon time if such files exist and were not downloaded. NOTE: If you're the Sysop, once you have a FileName entered at [U]tils prompt, you may press <Ctrl-E> to get to the same functions you'd have in the Sysop Menu for this particular file! Now for the menu selections of the File Section: FILEMENU_QUIT: (menu selection Q) This selection exits the FILE section and returns the user to the MAIN menu of the BBS. FILEMENU_INFO: (menu selection I) This selection displays information on a file. An example File Info follows: Filename: MAGCOM.ZIP File Area: E (This month's OS/2 uploads) Uploaded with YMODEM-G protocol Uploaded on 01/01/1990 at 06:41 Size is 80896 bytes File was downloaded 35 times Date of last access or download was 01/08/1990 Estimated download time: 5 minutes 24 seconds Brief (1-line) description: MAGCOM communications pgm for OS/2 from Gilmore Systems. X,Y,Zmodem MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-19 The FILES MENU Detailed Description Exists. Would you like to view it? (Y/N) => The "Estimated download time" will vary from user to user. Because Magnum stores each user's last CPS (file transfer rate), it uses that figure to determine how long it will take to download any other file on the system. If the caller calls back at a different baud rate, Magnum will adjust the user's stored CPS accordingly. All downloadable files have brief (1-line) descriptions associated with them. Some files have a detailed description associated with them. If you display [I]nfo on a file with a detailed description, Magnum will prompt you as to whether you'd like to view the detailed description. The detailed description can be up to 150 lines of text in length. If a file has a detailed description associated with it, the file will show up in the file listings as having a '+' character in column 1 just before the file's date. FILEMENU_LIST: (menu selection L) This selection will list all available files on the board (which the user's security level permits him/her to know about). Files which are password protected will not show up in the listings if the Sysop has configured the STARTUP for that node not to show password protected files. Each file listed takes up 2 text lines plus a blank line separating it from the next file. When choosing the [L]ist option, the following prompt will appear: Area(s) to list (? for help, blank to quit) => Note that prior to displaying this prompt, if the file PREDOWN.BBS exists, it will be displayed to the user prior to sending this prompt. This prompt requires the user to press their ENTER key after answering their prompt because it is not limited to a single-keystroke. By responding with the ? character, Magnum will list all available file areas authorized to be listed to the user. File areas are labeled from A to Z. The + or * character tells Magnum to list ALL areas authorized to be listed to the user. An example of a file appearing in a file listing follows (note that if the file had an expiration date, it would be displayed after the file size): + 01/01/1990 MAGCOM.ZIP 80896 DLs: 45 #204 MAGCOM communications pgm for OS/2 from Gilmore Systems. X,Y,Zmodem If a + character appears in column 1 (just before the file date), it signifies that a detailed description (up to 150 text lines) exists, which can be viewed by choosing the [I]nfo option. The rest the file description in a list command shows the date of upload, filename, filesize, it's expiration date (if any), number of DownLoads, the file number, and a one-line description of the file. This information is shown for every file appearing in a file List command. If a user wanted MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-20 Using Magnum BBS as a USER The FILES MENU to list more than one file area at a time (but not all areas), they would enter the areas pertaining only to what they wanted to see. For example, if the user wanted to list just areas C, H, K and L, they'd respond to the following prompt as follows: -> Note that the file number (#204 in this example) can be used in -> response to any prompt requiring a file name, instead of the file -> name (answer the prompt with #204, not 204). Note that file numbers -> will change after anytime you perform a 'pack' of the file database. Area(s) to list (? for help, blank to quit) => CHKL Note that responses of "C,H,K,L" and "C H K L" (without the quotes of course), are also valid responses. Only 26 characters are allowed in response to this prompt - therefore, any commas (,) or spaces ( ) imbedded in the user responses are extraneous and unncessary. NOTE: When listing files by area, Magnum searches the DISPLAY DIRectory for a matching FDIR_x.BBS (or FDIR_x.SCR) file, where 'x' is the same letter as that of the file area about to be displayed. For example, if the user replied to the above prompt with EHK, then Magnum would first display FDIR_E.BBS (if it exists) prior to displaying the files in area E, then FDIR_H.BBS (if it exists) prior to displaying the files in area H, then FDIR_K.BBS (if its exists) prior to displaying the files in area K. FOR USERS OF THE 'EXTENDED FILEBASE' MODULE: When in an 'extended' FileBase [a FileBase other than 0 (main)], Magnum searches the DISPLAY DIRectory for a matching FDIRcnnn.BBS (or FDIRcnnn.SCR) where 'c' is the File Area (A-Z) of FileBase nnn (where nnn can be 001 to 255). Note that nnn must ALWAYS be 3 digits. If the matching file exists, Magnum displays it prior to listing the files in that area. For example, if the user is in FileBase 3 and wishes to list the files in area C of that FileBase, then Magnum will search for FDIRC003.BBS and display it prior to listing the files in area C of FileBase 3 if found. If not found, Magnum will simply go ahead and display the files in area C of FileBase 3. If logged on locally, or if snooping on a remote session, you'll see a message something like << File FDIRC003.BBS Not Found >> on your console (this will not show up on the remote user's end. Also, in response to any filename prompt, if using the Extended FileBase, a user may supply a filename any of four ways: FILENAME.EXT FILENAME.EXE:base #nnnnn #nnnnn:base Note that if they append the :base (ie: "filename.ext:2" for the file "filename.ext" in filebase 2), Magnum will switch to filebase MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-21 The FILES MENU 2 in order to access the file. File can be "marked" from any combination of FileBases. FILEMENU_DL: (menu selection D) This selection allows a user to download one or more files from the BBS. If the user has not selected a default file transfer protocol (via [E]nvironment selection from main menu), the user will be prompted to choose a transfer protocol for this download: Single: X=Xmodem, C=Xmodem-CRC, 1=Xmodem-1K Batch: Y=Ymodem, G=Ymodem-G, Z=Zmodem, Q=Quit Transfer protocol (X,C,1,Y,G,Z,Q) => Once a download protocol has been established (note that Ymodem-G is dissallowed by Magnum if the user has not made an error-correcting modem connection - ie: MNP, ARQ, etc), the user will be prompted for the filename(s) of the file(s) s/he wishes to download. If the file transfer protocol chosen is a Single-file protocol, only one filename will be accepted. If it's a Batch protocol, up to 50 filenames will be accepted. When the user supplies a filename, Magnum makes sure the file exists in it's file database - if it does, Magnum displays the size of the file and estimated download time of the transfer. If it does not exist, Magnum informs the user of this. If the user supplied a file extension of .ARC when it should've been an extension of .ZIP (or vice versa), Magnum corrects the entry and informs the user. Magnum will not allow the same filename to be entered twice in any given Batch download (just in case the user forgot that s/he already chose the file for download). NOTE: Multiple filenames can be supplied at any Filename prompt (if you choose a Batch protocol such as Ymodem, Ymodem-G or Zmodem) by leaving a space between filenames. If using the extended FileBase module, filenames not in the current FileBase can be specified by entering: filename.ext:bbb or: #nnnn:bbb where :bbb is the filebase (and #nnnn is the file-number). Note that once :bbb is specified, the actual filebase is changed to bbb in order to find that file! Magnum will inform the user to start the transfer at their end once the filename(s) for download have been completed. The user must refer to their communications program's documentation for how to invoke a file transfer with their software. Some communications programs such as our MAGCOM program will automatically start a Zmodem file download - no interaction with the user is required (not applicable to MAGCOM version 1.0). Zmodem Crash Recovery is supported by Magnum on aborted downloads. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-22 Using Magnum BBS as a USER The FILES MENU If logged on locally (console), Magnum will prompt you for a filespec to download (local copy) to. You may respond with just a pathname terminated by the \ character, Magnum will simply copy the file to that path; however if you supply a filename.ext after the path, Magnum will use that instead. Example: Filename to Download => MAG8DEMO.ZIP Copy to [d:][\path]filename[.ext] => C:\DLDIR\ When the file transfer is over, Magnum informs the user their CPS (characters per second transfer rate) if successful, otherwise Magnum will display a "Xfer Failed or Cancelled" message. NOTE: Calculation of CPS file xfer rates on small files are simply not an accurate reflection of CPS rate due to the nature of trying to measure CPS rate on a small file. Therefore, Magnum will only calculate the CPS rate of a file xfer if the file size is at least 5 times the baudrate of the connection. For example, a 2400-baud caller will have CPS rates calculated only for files whos sizes are 12,000 bytes or higher. FILEMENU_UL: (menu selection U) This file selection allows a user to upload a file to the BBS. The user will be presented the following series of prompts: Filename you will upload? (blank quits) => Note that prior to displaying this prompt, if the file PREUP.BBS exists, it will be displayed to the user prior to sending this prompt. At this point, the user will enter a filename for upload. Magnum then checks to see if the file exists in the database. If it does, the upload will be disallowed. Magnum will also check to see that the filename is not CMD.EXE, COMMAND.COM, or a device name - if it is, the upload is disallowed. Magnum also checks to see that the filename does not contain special characters (ie: <, >, |, etc) and that the filename extension does not exceed 3 characters (to the right of the . character), and that the filename does not exceed 12 characters (including the . character). Magnum also searches BADUPLD.LST in your SESSION DIRectory (if it exists) to make sure it's not in the bad upload list (see BADUPLD.LST in the description of files in the SESSION DIRectory). NOTE: if the filename you supply already exists and you are the original uploader of the file (or the sysop), you may reupload the file - Magnum will retain the old description and any extended description. Once Magnum has determined that the filename supplied is a valid upload filename, it will prompt the user for an upload protocol (unless the user has a default protocol selected in their environment). Note that Magnum only allows 1 file to be uploaded at any given time even if the upload protocol being used for the transfer is a Batch protocol. Next, Magnum will prompt the user for a one-line description of the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-23 The FILES MENU file: Please enter a one-line description of the file: Next, Magnum will prompt the user as to whether the file should be password protected: Do you want this file password protected? (Y/N) => Next, Magnum will prompt the user for an expiration date: Do you want an expiration date for this file? (Y/N) => If the user selects Y, an expiration date prompt will appear, and the file will be deleted as of 00:00 on the expiration date. Next, if the user is allowed to upload to more than one file area, the following prompt will appear: Save file to which area? (? for list) => When the user answers this prompt, Magnum will display how many bytes are available on the upload disk drive containing the directory which will house the upload. Next, Magnum will prompt the user as to whether they'd like to leave a detailed description of the file: Would you like to leave a more detailed description of the file in message form? (Y/N) => If the user answers with Y, Magnum will invoke the line editor for the user to enter up to 150 text lines describing additional information about the file. Next, Magnum informs the user that it's ready to receive the file - it tells the user the filename and protocol it expects. Note that if you're logged on locally (console), Magnum will prompt you for the source filename for a local copy. NOTE: When logged on locally (console), the source filename for the local copy may be specified as a pathname terminated by the \ character (Magnum will append the filename you supplied to the path prior to the copy). Example: Filename to Upload => MAG8DEMO.ZIP Copy to [d:][\path]filename[.ext] => C:\ULDIR\ Once the transfer completes successfully, Magnum checks the file by calling the CHKANSI.EXE program - if it finds any ANSI escape sequences which redefine a keyboard key, it locks the user out of the system and disconnects. If the check is successful (no harmful escape sequences found), Magnum then checks to see if the uploaded filename is a .ZIP file - if it is, it checks to see if the file ZIPCMT.x exists (x=node number user is on) - if it exists, it adds the contents of that file to MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-24 Using Magnum BBS as a USER The FILES MENU the .ZIP file as a ZIP comment. Magnum then adds the file entry to the database and displays the user's CPS transfer rate and compensates the user (if defined) with time spent for the upload, and gives the user credit for the upload. NOTE: In the event of Magnum locking out a user due to an upload containing harmful ANSI escape characters which will redefine keyboard key(s), Magnum will generate a message to the Sysop about this action. Because compressed files (ARC, ZIP) can sometimes reproduce this ANSI pattern, CHKANSI.EXE will lock the user out of the system even though there may not be any ANSI escape sequences to redefine the keyboard when the file is uncompressed. -> If you wish to disable this automatic checking of ARC, ZIP or -> files with other extensions, see the description of NOANSCHK.LST -> in the chapter entitled "Back to Display Files & Subdirectories", -> in the "SESSION Directory" section. If the uploaded file has an extension of .ARC or .ZIP, Magnum performs an integrity check on the file. If the integrity check fails, Magnum automatically deletes the file and no upload credit is acknowledged. NOTE: If the user uploads a .ZIP file which contains the member FILE_ID.DIZ, Magnum will automatically extract that member and use it as the extended (long) description. FILEMENU_NEW: (menu selection N) This menu selection is identical to the [L]ist selection except that it only lists files since the last time the user selected the [N]ew files selection. NOTE that Magnum stores 27 separate dates for this selection for each user. It stores the date this selection was last used for each of the 26 different file areas (A to Z), and for the + (all files) selection. The prompt also gives the user a chance to override the default date. When [N]ew Files is selected, the following prompt appears: Which area (A-Z, + for all, ? for list, blank to quit) => Once the user enters this prompt, another prompt appears which will look similar to the following: Enter date MM/DD/YYYY (default = 01/08/1990) => Note that if the user has chosen [E]uropean date formats, the MM/DD/YYYY would appear as DD.MM.YYYY to the user. This applies to all date prompts on the system. If the user supplies a date in response to this prompt, that date is checked and will be used instead, otherwise, if the user simply presses ENTER, the default date displayed within parenthesis will be used instead. The listing which will appear after answering this prompt will have the same format as that used by the [L]ist Files menu selection. FILEMENU_SRCH: (menu selection T) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-25 The FILES MENU This menu selection allows the user to perform a text search of files on the board. The text search searches both the filenames and descriptions in it's search. When this menu selection is chosen, the following prompt appears: Which area to search (A-Z, + for all, ? for list, blank to quit) => Once the user answers this prompt with one of A-Z or +, the following prompt will appear: Text to search for (blank quits) => Assuming the user supplied a non-blank answer to the prompt, the next prompt will appear: Files newer than (MM/DD/YYYY) (default=01/01/1980) => The user can either accept the default date by pressing ENTER, or supply a different date. Once this prompt has been answered, Magnum will search the files database and display (in [L]ist Files format), a list of all files (if any) it finds matching the text supplied by the user. Both file description and filename fields are searched for a match. Note that the search is case independent, meaning that uppercase/lowercase is not an issue (ie: Graphics, graphics, and GRAPHICS are identical as far as Magnum is concerened). Note that any matches in a filename will result in the 'matching' portion of that filename being displayed in lowercase. Any matches in a file description will be bracketed (within < and > characters). At the end of the list of files matching the search criteria (if any), Magnum displays the "Press ENTER to continue ..." prompt. If the & or | character appear within a search string, it has special meaning, and only the (brief) file description (not the filename) will be searched for a match: - If the & character is part of the search string, it separates AND text to the left and right of this character as two separate search strings. If BOTH search strings are matched in the brief file description, a match is made. - If the | character is part of the search string, it separates OR text to the left and right of this character as two separate search strings. If EITHER search string is matched in the brief file description, a match is made. Examples: - CAT&MOUSE Will match any files who's brief (1-line) description contains BOTH the words CAT and MOUSE. - CAT|MOUSE Will match any files who's brief (1-line) description contains EITHER the word CAT or MOUSE. - CAT Will match any files who's filename or brief (1-line) description contains the word CAT. NOTES: - Only 1 & or 1 | character should be used within any search MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-26 Using Magnum BBS as a USER The FILES MENU criteria (although this is not checked). If any blank spaces appear to the left or right of a & or | character, they are considered to be a part of the search string! Do not use spaces before and/or after the & or | character unless you intend these spaces to be part of the search string! A handy use would be searching for the word ZIP but not as part of the filename! Whenever the & or | characters are used, the filename is not checked, only the description is, therefore to search for the word ZIP, supplying ZIP| would supply (note the absence of anything on the right of |). - Refer to FILESRCH.BBS in chapter 2 (DISPLAY DIR section). FILEMENU_STATS: (menu selection S) This menu selection presents the user with statistics on their upload/downloads performed both for the period and since they've first called the system. The list might look somewhat like the following: Your File Statistics: Your adjusted CPS (characters/second) transfer rate is: 256 Your upload areas: ACEFHIJKL Your download areas: ACEFHIJKLZ FREE download areas (not affecting UL/DL ratio): CFJ Your list areas: ACEFHIJKLZ Totals: You've uploaded about 30 Kbytes in 2 files You've downloaded about 102 Kbytes in 6 files You've downloaded 2 files from FREE download areas Your totals for the week: You've downloaded about 0 Kbytes in 0 files Maximum allowed: 70000 Kbytes or 700 files Note that "Your totals for the week:" is displayed to those who have a period type of "Weekly". "week" would display as "day" to daily users, "month" to monthly users, and "year" to yearly users. FILEMENU_GOODBYE: (menu selection G) This menu selection is identical to the Goodbye selection in any other menu (main menu, message menu, etc). It firsts prompts the user for a confirmation of their intentions to log off, then prompts the user for whether they wish to leave a Comment to the sysop (see the VERIFY_GOODBYE option in the STARTUP file). FILEMENU_HELP: (menu selection ?) This menu selection will display the file FILEHELP.BBS in the HELP directory if it exists, otherwise it will display a "Help not available" message. FILEMENU_EXT: (menu selection A) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-27 The FILES MENU This menu selection (EXT stands for EXTernal programs) allows the user to Access a compressed (ARC or ZIP) file. The user can view the list of members within a compressed file, read any readable members, or download any of the members within the file. This selection does not require a file extension (ie: .ARC, .ZIP, etc) - it will find the file matching the first acceptable extension. By 'acceptable extension', we mean .ARC and .ZIP (built in). You can add support for additional compressed file formats (which Magnum will recognize and process) by creating or updating the file COMPRESS.LST in your SESSION DIRectory. -> If you wish to provide Magnum with compression formats in addition to -> .ARC and .ZIP compression formats, refer to the description of -> COMPRESS.LST in the chapter entitled "Back to Display Files & -> Subdirectories", in the "SESSION Directory" section of that chapter. FILEMENU_READ: (menu selection R) This menu selection allows the user to read a non-binary file. A non-binary file is a file containing only readable text (ie: files with extensions of .EXE, .COM, .SYS, .DLL, .ZIP, .ARC, etc are binary files and not readable). If a file is read in this fashion, rest assured that any imbedded MILC commands (either intentional or non-intentional) are ignored (not processed). FILEMENU_CHANGE: (menu selection C) This menu selection allows the user to change a file they uploaded. First, Magnum will prompt the user for the filename: Name of file to change? (blank quits) => If the user supplies a filename they didn't upload, Magnum will disallow any changes. Otherwise, a display similar to the following would show: File was found in area "E" Filename: "MAGCOM.ZIP" - Area: "E" - Public Expiration Date: None Detailed Description: Does not exist 1-line Description: MAGCOM communications pgm for OS/2 from Gilmore Systems. X,Y,Zmodem 0) Quit 1) Delete 2) Change Area (E) 3) Make Private (password protect) 4) Change FileName (MAGCOM.ZIP) 5) Change Expiration Date () 6) Change Brief (1-line) description 7) Add Detailed Description Choice (0-7) => MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-28 Using Magnum BBS as a USER The FILES MENU The above submenu is self-explanatory. The user can change 7 different things for any file they've uploaded. FILEMENU_MAKELIST: (menu selection M) This menu selection is identical to the [N]ew Files selection, except that it's output is compressed into a .ZIP or .ARC file (depending on the user's Environment default for System Compression Type). The resultant .ZIP or .ARC file is password protected with the user's logon password, and placed in the RJE file area for download. It is automatically marked with an expiration date of the next day. If the user downloads the file successfully before midnight, the file is deleted immediately. This menu selection creates an up-to-date list of all files available for download on the BBS (which the user is authorized to download). Note that the created filename has the format Uxxxxx@y.ZIP (or .ARC) where xxxxx is the user's ID number (up to 5 digits), and y is a hex number ranging from 0 to F indicating how many of these RJE files s/he created today. If y is 0 this is the first file, if y is 5 this is the 6th file. If y is F this is the 16th file and Magnum will disallow creation of any more RJE files for this user until the next day. Note that downloadable file listings do not contain file numbers (#nnnn) because these numbers are subject to change when the sysop packs the file database(s). Also, the extended (long) descriptions are included in the downloadable listings IF this feature is enabled by the user ([E]nvironment option #26). FILEMENU_OPT1: (menu selection 1) FILEMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file FILEOPT1.BBS or FILEOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. FILEMENU_BASE: (menu selection F) This menu selection is for those who've purchased [and installed] our 'Extended MessageBase' module. If you're not using this module, you should raise the security level of this menu option such that it does not appear on any user's screen. FILEMENU_UTILS: (menu selection E) This menu selection is identical to choosing the [U]tils selection when at the "- More -" during file listings. This selection allows the user to mark files, unmark files, access compressed files, obtain detailed information on files, modify their list of marked files, etc. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-29 The FILES MENU NOTE: If you're the Sysop, once you have a FileName entered at this prompt, you may press <Ctrl-E> to get to the same functions you'd have in the Sysop Menu for this particular file! FILEMENU_BASEUP: (menu selection +) FILEMENU_BASEDN: (menu selection -) These menu selections are to be used with the optional Extended FileBase module. These commands are a 'shortcut' for a user to move to the next available FileBase or next preceding FileBase s/he has access to. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-30 Using Magnum BBS as a USER The SYSOP MENU The SYSOP MENU currently has 11 menu selections available: SYSMENU_QUIT: (menu selection Q) Like any other QUIT MENU command, selecting this menu option will return the user to the main menu. SYSMENU_CMD: (menu selection O) This menu selection will invoke the operating system's CMD.EXE (OS/2's command interpreter). This is available whether the user is on locally or remotely. To exit the command interpreter and return to the BBS, enter the command EXIT followed by your ENTER key. SYSMENU_PRINT: (menu selection P) This menu selection gives you the option of printing the user database (one page per user) or address lables. Choosing this menu selection results in Magnum prompting you for which filename or device to print to. In most systems, PRN is the device name of the printer. If you specified a filename instead, output will be printed to that filename. The next prompt you will see asks which security level you wish to print. The prompt after that asks if you want [R]ecord information or [A]ddress Labels to print. If you choose [A]ddress Labels, you'll get a "[P]rint, [A]lignment" response. By choosing [A]lignment, Magnum will print 2 dummy labels on your printer, giving you a chance to align the labels in your printer. Once you're satisfied with the alignment, choose not to reprint the test - Magnum will then print the address labels. Note that you can press <Ctrl-X> during printing to abort. If you're printing address labels, it's recommended to set your printer in condensed mode. Magnum assumes 6 lines between labels and assumes each label can hold 5 lines of address information (the 6th line is a blank line separating labels). NOTE: You may also print out "Mail" accounts. SYSMENU_MSG: (menu selection M) This menu selection allows the user (sysop) to fiddle with the message database. When you select this option, the record for the first message on the system is displayed along with the prompt for this area. The display might look similar to the following: MSGBASE: 0 RECNUM: 0 (actual), 0 (recorded) DELETED: N CONF: H PRIVATE: N RECEIVED: N, MSGMILC: '@', ECHO: N FROM: /0 (CHUCK B GILMORE) TO: /55 NUM: /0 #READ: 68 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-31 The SYSOP MENU SUBJ: Welcome! DATE: 09/01/1994 TIME: 06:00 FROM_PSERNUM: 1234567890 EXPDATE: (nul) TO_PSERNUM: 1234567890 CC: N SENT: Y FWD: N FROM_USERNAME: "CHUCK B GILMORE" RECEIPT: N TO_USERNAME: "JOHN S. DOE" REPLIES: N ISREPLY: N RECVD_DATE: (nul) RECVD_TIME: (nul) FILENAME: H9010916.835 FIELDNAME, Next, Quit, Prev, Match, Ref, Erased, Hardcopy, #nnnn, Base, From, To, Userid, Date, Subj, View => The fields listed are all changeable except for the RECNUM field which is merely an informative field for your information only. To change any of the fields, enter the full fieldname. For example, to change the SUBJ field, type SUBJ followed by your ENTER key. You'll get a prompt asking for the new SUBJ which you might respond with "Welcome to Magnum BBS!". You can change any of the fields simply by entering the name of the field and pressing ENTER - Magnum will then prompt you for the new value of the field. All fields which hold one of two values (Y or N for Yes or No) are called boolean fields (boolean refers to fields which can hold one of two things - Yes or No, or programmers are more familiar with TRUE or FALSE). Except for the CONF: field which can hold any alphabetic value, boolean fields can be interpreted (via example) as: DELETED: N simply ask yourself a question with the fieldname - Is this message DELETED? The value shows N, therefore, NO, the message is NOT deleted. Let's try it with another boolean field: ISREPLY: N simply ask yourself Is this message a reply (to a previous message)? The value shows N, therefore, NO, the message is NOT a reply. Since the values for the fields are self-explanatory once you understand what the fieldnames refer to, let's describe what each fieldname refers to: MSGBASE: Will always be 0 unless you're using the optional 'Extended MessageBase' module, otherwise can be 0 to 255. RECNUM: Not Changeable - for your information only DELETED: Boolean field (Y=Deleted, N=Not Deleted) CONF: Conference area of message (one of A to Z) PRIVATE: Boolean field (Y=Private, N=Not Private) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-32 Using Magnum BBS as a USER The SYSOP MENU RECEIVED: Boolean field (Y=Received by addressee, N=not received) MSGMILC: Shows the MILC command character used for this message. This does not necessarily mean that any MILC commands were used. ECHO: Shows whether this message is echoable (Y) or not (N) to other systems. Echoable messages generally have different 'from' and 'to' serial numbers. FROM: Who composed the message (ie: /0 (CHUCK B GILMORE)) TO: Who the message is to (ie: /IDNUM (Firstname M, Lastname) or ALL) NUM: IDNUM of original addresse (if this is a CC or FWD message) #READ: Number of times message was read. SUBJ: Subject of message. DATE: Date of message TIME: Time of messaage FROM_PSERNUM: The serial# of the originating BBS (usually yours). TO_PSERNUM: The serial# of the target BBS (usually yours). SENT: If the 'from' and 'to' serial numbers are identical, this field will always be Y (yes). However, if the 'from' and 'to' serial numbers are different, it will be Y (yes) only if the message has been sent via AMMO (refer to chapter on Magnum-to-Magnum Remote Mail), otherwise N (no). EXPDATE: Expiration date of msg (MM/DD/YYYY or DD.MM.YYYY) or (nul) CC: Boolean field (Y=this is a CC (carbon copy), N=this is not a CC) FWD: Boolean field (Y=this is a forwarded message, N=not forwarded) RECEIPT: Boolean field (Y=receipt requested, N=no receipt requested) REPLIES: Boolean field (Y=replies exist, N=replies do not exist) ISREPLY: Boolean field (Y=this is a reply, N=this is not a reply) RECVD_DATE: Date msg was received (MM/DD/YYYY or DD.MM.YYYY) or (nul) RECVD_TIME: Time message was received FILENAME: Filename of file holding actual text of message (same as REF# but with the . to delimit the filename extension). Note that the first character of the filename determines which subdirectory (A-Z) of the MESSAGE subdirectory MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-33 The SYSOP MENU houses the file. This explains the FIELD entries. The actual prompt: FIELDNAME, Next, Quit, Prev, Match, Ref, Erased, Hardcopy, #nnnn, Base, From, To, Userid, Date, Subj, View => expects you to enter either a FIELDNAME, or one of the 6 command letters (N,Q,P,M,R,E,F,T,U,D,S,V). The command letters are defined as follows: N = Next. Show next message entry (wraps to 0 if at end of database). Q = Quit. Quits message database section and returns to Sysop menu. P = Prev. Show previous message entry (wraps to last entry if at beginning of database). M = Match. Prompts for a Conference letter to match. All Next and Prev commands will only display the records who's conference area matches what you've supplied here. R = Reference#. You can supply a reference# here and Magnum will bring up the record for that message. E = Erased. Magnum will only display records for those messages which have been erased (deleted). If you haven't done a "[S]tatus of Databases" command, then erased messages should still be Viewable (with the View command), otherwise the message really is deleted (refer to the DELETED field). H = Hardcopy. Prints message on your printer, unprocessed. #nnnn = Record number to 'jump' to (start with the # character). B = Base. If using the optional 'Extended MsgBase', you can change the MsgBase here. F = Only display records who's FROM field matches the FROM ID you'll supply in answer to this prompt. T = Only display records who's TO field matches the TO ID you'll supply in answer to this prompt. U = Only displays recrods who's FROM or TO field matches the user ID you'll supply in answer to this prompt. D = Date. Only displays records which are greater than or equal to the date answer you'll supply in answer to this prompt. S = Subject. Only displays records which match the Subject field you'll supply. V = View the message text. This is identical to reading the message when in the "Read Messages Submenu". The difference is that when you choose the View option from here, Magnum will not update the message header (ie: won't count it as being read or received, and no receipt will be generated if the message is to you with a receipt requested). As you can see, the Message Database area of the Sysop menu can be a very powerful utility. You can change most any field of any message header. NOTE THAT ALL CHANGES MADE TO "FROM" AND "TO" MUST START WITH THE '/' CHARACTER (note that a recipient of ALL is designated as /-1). Note that if you choose 'H' (hardcopy), you will be prompted for a file or devicename to print the message out to. Printing will print any imbedded MILC commands unprocessed. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-34 Using Magnum BBS as a USER The SYSOP MENU SYSMENU_USER: (menu selection U) The USER DATABASE area of the Sysop Menu is another powerful sysop tool. When you enter this area of the Sysop menu, the record for ID /0 (Sysop) will automatically be displayed. As with the Message database area, ANY fieldname (with the exception of the USER ID) is changeable. An example user record might look something like the following: LASTNAME=DOE, FIRSTNAME=JOHN, MIDDLENAME=C ID=/0, STREET1(c)=John Doe's BBS, TYPE=U, REUSE=N, IA="id0" STREET2=12345 Abbey Road CITY=Los Angeles, STATE=CA, ZIP=90067, COUNTRY=USA FIRSTCALL=10/05/1989, LASTCALL=01/12/1990, TIMELAST=18:24 PASSWORD=NHOJ, DOB=07/01/1958 (age: 31), DATEFORMAT=U, RJEJOBS=3 PHONE1=213-555-1234, PHONE2=213-555-4321 CPUTYPE=IBM PS/2 model 80, CONFERENCES=ACEFGH MEMODATE1=, MEMODATE2=, PRIVMSG=Y, DELMSG=Y, SUB_FILEDEL=N SYSOP_COMMENT=Master SYSOP XFERTYPE=N, PERIODTYPE=W, EXPERT=N, LOCKED_OUT=N, COLOR=Y, DISPLAY_MO ERASE_MORE=Y, HOTKEYS=Y, LINES_PAGE=23, LEVEL=1000, UPLOADS=102 DOWNLOADS=36, CPS=2056, UDRATIO=0, TTL_CALLS=413, REMAINING=94 REMAINING_PERIOD=659, K_UL=4568, K_DL=2171, PERIOD_DL=700 PERIOD_K_DL=70000, DL_THIS_PERIOD=0, K_DL_THIS_PERIOD=0 DAILY_TIME=120, DAILY_DL=100, DAILY_K_DL=10000, PRIVACY=OFF FILE_U_AREAS=ACEFHIJKLSZQ, FREE_DL_AREAS=CFJ FILE_D_AREAS=ACEFHIJKLSZQ, FREE_DOWNLOADS=1 FILE_L_AREAS=ACEFHIJKLSZQ, FILEGRP=0, FILEBASE=0 MSG_R_AREAS=ACHKLSWZ, MSGGRP=0, MSGBASE=0, RMAIL=N MSG_W_AREAS=ACHKLSWZ, OMAIL=N MSG_L_AREAS=ACHKLSWZ MILC_CMDS=ABCDEFGHIJKLMNOPQRSTUVWXYZ, COMPRESS=Z, PRIVM=108, PUBLM=34 I= OS/2 PM COMMUNICATIONS BBS COMMAND (FIELDNAME, Quit, Match, Nxt, Prev, Srch, Del, /ID) => The last line of the display (in hi-intensity cyan on color systems) prompts you for either a FIELDNAME or the first letter of one of the 6 commands (Quit, Match, Nxt, Prev, Srch, Del), or the ID number (beginning with the forward slash (/) character) of the user who's record you'd like to bring up. If you are seeing the display in color, FIELDNAMES appear in hi-intensity green, while their changeable values appear in hi-intensity white. Note that any field (with the exception of ID) can be changed. The ID number is identical to the record number (position in database file), which is why the user database is not packable (unlike the file and message databases which are packable). We've already explained what supplying a forward slash and user ID does, so lets explain the other 6 commands. Only the first letter of the other 6 commands need be supplied (ENTER key is required after making any selection here). The Quit command quits the User Database area and returns you back to the Sysop Menu. The Match command prompts you for a security level (or match on MAIL accounts) - after you answer that prompt with a security level, Magnum will display only those users in MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-35 The SYSOP MENU the database who's security level matches the one you just supplied - this will be true for the Nxt and Prev commands as well - use the Quit command to stop the Match process. The Nxt command will bring up the next record in the user database - if you're already at the highest record number, it will wrap to record 0. The Prev command will bring up the previous record number - if you're currently at record number 0 (ID of /0), it will wrap to the last record (highest record number) in the database. The Srch command will invoke the User Search command which is identical to the MAINMENU_USERS (main menu selection U) command. The Del command will prompt you as to whether you wish to delete this user - if you delete the user, you can undelete them later by issuing the /ID command and answering Yes to the "undelete" prompt (unless the user id has been re-assigned to a new user). The FIELDNAME's are all self explanatory. Simply enter the FIELDNAME of a field you wish to change. A prompt for the new fieldname will appear asking you for the new value to assign to the field. Note that if you wish to change the MIDDLENAME field of a user's record to blank (none), you'll need to change the MIDDLENAME to a value of X (the letter X). Note that if you are changing a user's record and that user happens to be online at the same time, all fields will accept and apply the change except for the LEVEL field. To change the security level for a user who's already online, you'll need to change it at the MBBS sysop console with the "x LEVEL yyyy" command (where x is the node they're on, and yyyy is the new security level). Note that MEMODATE1, MEMODATE2 and SYSOP_COMMENT are for your (Sysop) private use - you may do with these fields as you wish. The memodate field is typically used when you're running your BBS as a subscription BBS system. You would enter the user's subscription expiration date in this field and use MBBSEXEC.EXE (see the chapter on MBBSEXEC) sysop utility to lower this user's security and access levels on the user's expiration date. The only other field that needs some explaining is the MILC_CMDS field. Refer to the chapter on MILC commands. This field contains the letters (A-Z) of allowable MILC commands the user can use in message text. Typically this value is "AO" (@A commands are for color, @O commands are for other, miscellaneous information display). In this case, the Sysop's record is being displayed, and the Sysop should be able to issue ANY MILC command within any message text s/he likes - therefore, all letters of the alphabet are defined (even though there aren't that many MILC categories - this way, you won't have to change it for future releases of Magnum which may contain additional categories of MILC commands in the future). If a user enters a MILC command in a message text which isn't allowed (not in the MILC_CMDS of the user's profile), Magnum will simply display the MILC command when someone reads the message as though it were normal text but it won't process it. Other fields which may need additional explanation: The STREET1 field will be followed by (c) or (h) to reveal whether the STREET1 field is referring to Company Name or Handle (alias name). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-36 Using Magnum BBS as a USER The SYSOP MENU The REUSE and TYPE fields appear near the top of the screen (after STREET1). The IA field is for "Internet Adress", and the FILEGRP and MSGGRP appear near the bottom (after FILE_L_AREAS and MSG_R_AREAS). Note that FILEGRP, MSGGRP, FILEBASE and MSGBASE apply to those sysops using the extended FileBase and/or Extended MsgBase modules. Note that TYPE applies to those sysops using the Magnum Remote Mail option. TYPE can be one of U (user) or M (mail). REUSE can be one of Y (yes) or N (no) - If N (no), this record is NOT reusable in the event you delete this user. The RMAIL field indicates whether the user can enter a message to a user on a remote Magnum system. The default is NOT to have this capability, however you may change this default for any/all users either individually in the User Database area of the Sysop Menu, or in bulk with a .MEX program. For those running the extended file or msgbase modules, refer to the chpater on Extended Filebase and Extended MsgBase modules. The OMAIL field (Outside Mail) indicates whether the user has access to/from the "outside mail" account refer to the chapter "Outside Mail". SYSMENU_FILE: (menu selection F) This menu selection will enter the Files database. First, you'll see the following prompt: B)ase, F)ile Utils, A)dd Files (B,F,A) (blank quits) => By simply pressing ENTER (without entering a response), you'll quit this section and go back to the Sysop Menu. By choosing B, you'll be allowed to change the FileBase (applicable only if using the optional 'Extended FileBase' module). By Choosing F, the following prompt will appear: Search by A)rea or F)ilename (A,F, blank quits) => By choosing A, you'll be prompted for a file area (A-Z) in which to add a file from. The file must already exist in that file area! By choosing F, the following prompt will display: Search by A)rea, F)ilename or U)ser (A,F,U - blank quits) => If you choose A)rea, then the records matching that file area will display in sequential order, starting with the first one it finds. You'll be given a chance to modify any of the fields in any of the records while it's being displayed, or you can go on to the next record matching the file area, or quit. If you choose F)ilename, the record of the filename will appear. If you choose U)ser, then all files uploaded by that user (filenames only), will be displayed. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-37 The SYSOP MENU When a file record is displayed, it might look like the following: FileName: "MAGCOM.ZIP" - Area: "E" - Public Expiration Date: None Detailed Description: Does not exist 1-line Description: MAGCOM communications pgm for OS/2 from Gilmore Systems. X,Y,Zmodem 0) Quit 1) Delete 2) Change Area (E) 3) Make Private (password protect) 4) Change FileName (MAGCOM.ZIP) [#204] 5) Change Expiration Date () 6) Change Brief (1-line) description 7) Add Detailed Description 8) Upload method (G) 9) File Date (01/01/1990) 10) File Time (06:41) 11) Last Accessed (01/08/1990) 12) ID# of uploader (/0) 13) Delete detailed description (NonApplicable) 14) Size of file (80896) 15) Number of downloads (67) 16) FileBase (000) 17) View ZIP Choice (0-17) => Note that choices 0-7 are identical to the FILEMENU_CHANGE (file menu option C) except that choices 8-17 have been added for the rest of the record to be available for changes by the sysop. All parameters here are self explanatory. When you quit (0) this selection, you will return to the previous prompt - if you're searching by area, you'll be prompted as to whether you wish to see the record of the next file in the area or if you'd like to quit. The other selection of the Files Database section of the sysop menu is the A)dd files selection. Choosing this option first requires that the file you are about to add has been placed in the directory matching the file area you wish to add the file to. In other words, if file area F is defined as "E:\MAGNUM\NEWFILES", then the file you are about to add to the database should already be placed in this directory. By choosing the A)dd files selection, you will be prompted for the name of the file you are about to add, followed by a prompt for the area the file is to be found in, and a description of the file. SYSMENU_ACTIVITY: (menu selection A) This menu selection is actually two different functions in one. The main purpose for this function is to view the activity logs for the individual nodes. The prompt appearing when you select this option is as follows (we're assuming 4-node version): MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-38 Using Magnum BBS as a USER The SYSOP MENU Activity for which node (1-4) => By supplying a node number, the log for that node will be displayed (BACKWARDS) in reverse chronological order. If you anser the prompt with a question mark (?) followed by a node number, for example: Activity for which node (1-4) => ?1 you will be placed in "Remote Snoop" mode. In other words, you will be able to see everything the user on that node sees. This is intended for sysops who are logged on remotely and wish to "snoop" on someone as though they were sitting at the master console and typed "1 switch". To end "remote snoop", simply press <Ctrl-X>. Important notes about "remote snoop": Characters are placed in a circular buffer of 2k bytes. If you are logged on at a lower baud rate than the user you are "snooping" on, you may experience loss of characters in this mode. Also, if the user is performing a file transfer (upload or download), the usual display of "Bytes Sent" or "Bytes Received" will not be visible! Do not be alarmed at this. Do not try to use this "remote snoop" facility while logged on locally - a decrease in priority is issued to the local node and you will lose MANY characters of snoop display. SYSMENU_REMOTE: (menu selection R) This menu selection will work only for sysops who've logged on remotely (will not work if logged on locally via the console). This area of the BBS emulates the MBBS Sysop console. You can issue ANY MBBS command that you'd ordinarily have to be sitting at the Sysop console to issue. You can make any node(s) active, inactive, schedule a node for shutdown, force a user off, etc. The only thing you can't do is issue the "* logon" command (it will be rejected). When you first enter this menu selection, Magnum will send the "MAGNUM SYSOP CONSOLE Display Screen" to your remote terminal, and prompt you for a MBBS command. After any command you enter, it will be processed and the "MAGNUM SYSOP CONSOLE Display Screen" will be redisplayed on your remote terminal. To end this "remote sysop console" mode, simply ENTER a null command (just press ENTER without typing anything at the command prompt). NOTE: "TEST mode" is not possible via this option - it is available only at the sysop's console (keyboard) on the machine running Magnum. SYSMENU_STATS: (menu selection S) This menu selection displays the status of the databases. NOTE: BY CHOOSING THIS MENU SELECTION, ALL EXPIRED FILES AND MESSAGES WILL BE PHYSICALLY DELETED, NOT JUST MARKED FOR DELETION! ANY FILES OR MESSAGES MARKED FOR DELETION WILL BE PHYSICALLY DELETED! By choosing this menu selection, you'll see a display similar to the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-39 The SYSOP MENU following: MAGNUM OS/2 BBS - (C)Copyright 1989,1993 Gilmore Systems # Records = Active + Deleted USER DATABASE: 000647 000647 000000 (unpackable) FILE DATABASE: 000432 000414 000018 [FILEBASE: 000] <432> MSG DATABASE: 001407 001391 000016 [ MSGBASE: 000] <1407> RJE DATABASE: 001200 001200 000000 [F]=Pack File Database, [M]=Pack Message Database, [R]=Pack RJE Datab [C]hange File/MsgBase, [Q]uit Choice (F,M,R,C,Q) => Even though physical deletions are performed, an entry in the databases (File and Message databases) still exist for the deleted records. You must perform a Pack of the databases to recreate the databases - this will eliminate the deleted records and free up some space. For users of the Extended MsgBase and/or Extended FileBase modules: The information within the square brackets shows which base you're in, and the information within the angled brackets shows how many of the records actually belong to that base (you can have more than one base within the same .DAT file). IMPORTANT: WHEN PACKING DATABASES, MAGNUM WILL CAUSE ALL SESSIONS (OTHER THAN YOURS) TO TERMINATE. ALL NODES (EXCEPT YOURS) WILL ALSO BECOME INACTIVE. THIS APPLIES TO *ALL* SESSIONS AND NODES REGARDLESS OF WHERE THEY'RE LOCATED ON YOUR LAN. MAGNUM WILL GIVE YOU THE COURTESY OF PROMPTING YOU AS TO WHETHER YOU WISH TO CONTINUE WITH THE 'PACKING' BEFORE IT DOES ANYTHING - THIS WILL ALLOW YOU TO CHANGE YOUR MIND. THERE MUST BE ENOUGH FREE DISK SPACE TO HOLD AN EXTRA COPY OF THE DATABASE(s) YOU ARE PACKING! IT IS A GOOD IDEA TO MAKE A BACKUP COPY OF THE DATABASES PRIOR TO PACKING THEM. While packing message or file databases, the system displays + and - characters on the screen. A '+' character displays for every processed record, a '-' character for every record it deletes. At pack completion status is redisplayed, and the number of records in the database should should match the number of active records (deleted records should be 0). It's necessary to pack the databases periodically. Depending on how active your BBS is, we found that once per week suits most busy boards. NOTE: From time to time the number of records reported in the USER database will not match the number of actual records in the user database as reported by the "[V]iew System Statistics" from the main menu. This is normal, and eventually the two will match. The MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-40 Using Magnum BBS as a USER The SYSOP MENU number of records in this option is derived from the number of records in the USER.KEY file rather than in the USER.DAT file. The USER.KEY file will ocassionally contain more records than the USER.DAT file due to aborted NEW USER logons. You may switch to your SES_DIR and run SPLITLEY.EXE to correct this if you wish. SYSMENU_HELP: (menu selection ?) This menu selection displays the help file SYSHELP.BBS (in the HELP directory) if it exists, otherwise a "Help not available" message is displayed. As of this writing, a help file is not included for the Sysop menu, but you can feel free to write your own should you be inclined to do so. SYSMENU_GOODBYE: (menu selection G) This menu selection is identical to the GOODBYE function on any other menu. It prompts the user as to whether they're sure they want to disconnect, and whether they'd like to leave a comment to the Sysop prior to disconnecting (see the VERIFY_GOODBYE option in the STARTUP file). SYSMENU_OPT1: (menu selection 1) SYSMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file SYSOPT1.BBS or SYSOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Using Magnum BBS as a USER Page 7-41 The RJE MENU The RJE MENU currently has 8 menu selections available: RJEMENU_QUIT: (menu selection Q) Like any other QUIT MENU command, selecting this menu option will return the user to the main menu. RJEMENU_STATUS: (menu selection S) Choosing this menu selection will display the status of any RJE job(s) you started. First, you'll be prompted for a date which Magnum will use to start the search from. After you've responded to this prompt, the display might look similar to the following: (Seconds) (S e c o n d s) RJE_NAME START_DATE START STOP_DATE STOP TTL_TIME STATUS C L PID 50F0A12935 05/15/1990 12935 05/15/1990 12988 63 done 1 25 918 50F0A18043 05/15/1990 18043 running 1 25 926 The above example display shows the RJE_NAME (job name Magnum assigned), the date started, the time started (in seconds from midnight). If the job is still running, the STOP_DATE and STOP time will be meaningless, otherwise they'll be filled in. The STATUS tells whether the job is still running or whether its complete. C stands for priority CLASS, and L stands for priority LEVEL within the priority class. PID will only appear if the Sysop is listing the status of jobs, and will not appear for normal users. PID is the Process IDentification of the job. See the explanation of the @E command for further information. RJEMENU_LIST: (menu selection L) When a user selects this option, Magnum will display the RJELIST.BBS file (from your RJE DIRectory) if it exists. See our sample RJELIST.BBS file (in your RJE DIRectory for an example of how to put this file together). Upon exit of displaying this file, Magnum will run the program contained in MILC variable @Z0 with the parms in @Z1. It's suggested that you use the @E1 command to run RJE programs instead, and blank out the @Z0 variable prior to exiting this file (ie: @Z0=""); RJEMENU_DELETE: (menu selection K) Choosing this option will result in Magnum prompting you for the 10-character jobname of the RJE job you wish to kill (terminate). If the job is still active (running), Magnum will terminate it. RJEMENU_FILES: (menu selection C) This menu selection will list the completed RJE jobs ready for you to download, giving filename, creation date, expiration date, and size. RJEMENU_SYSOP: (menu selection X) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 7-42 Using Magnum BBS as a USER The RJE MENU This menu selection will allow the Sysop to perform the L and C options above but will be able to supply a user id instead of his/her own. The L option equivalent will also show extended information about the job, such as the program name, and the parameters which were used to pass to the program. RJEMENU_HELP: (menu selection ?) This menu selection will display the RJEHELP.BBS file from the HELP DIRectory. RJEMENU_GOODBYE: (menu selection G) This menu selection prompts the user as to whether they really want to end their session or not. If Yes, they are prompted as to whether they wish to leave a Comment to the Sysop prior to disconnecting (See the VERIFY_GOODBYE option in the STARTUP file). RJEMENU_OPT1: (menu selection 1) RJEMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file RJEOPT1.BBS or RJEOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This concludes chapter 7 "Using Magnum BBS as a User". After using the BBS as a Sysop for a while, you'll see why we chose to write the system as a text application rather than as a PM application. Because it's a text application, you can log on to your BBS remotely as Sysop from any terminal regardless of operating system and perform any sysop function you'd ordinarily have to be at the Sysop console to do. You'll find Magnum BBS to be a powerful, full-featured BBS when compared to other BBS systems. The remaining chapters in this manual deal with advanced Sysop functions. It is suggested that you become familiar and comfortable with everything covered so far before attempting to deal with the following chapters. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Magnum's ACE (Automatic Command Execution) Event Handler Page 8-1 Incorporated into Magnum BBS, is a powerful event handler known as ACE. ACE is an acronym for "Automatic Command Execution" because that's exactly what it does - automatically executes commands at predetermined days and times. When you first start Magnum BBS by starting the MBBS.EXE program, part of the MBBS.EXE startup routines look for a file by the name of MBBS.ACE in the PROGRAM directory (the same directory that MBBS.EXE is found in). This is why it's important that you make the current directory your PROGRAM directory prior to starting MBBS.EXE. If MBBS.EXE finds the file MBBS.ACE, it reads the file and stores or queues any ACE commands it finds within the file and issues a message similar "xx ACE commands queued". ACE commands are of two types: stored (queued), and immediate. Stored or queued commands are executed on predetermined day(s) and times. Immediate commands are those which are executed right away. When MBBS.EXE starts up, it will attempt to read the file MBBS.ACE (if it exists), and store the appropriate ACE commands within for later execution. MBBS.ACE is expected to be found in the PROGRAM directory - the same directory MBBS.EXE is in. MBBS.ACE is a normal text file which you create with your text editor. Blank lines are ignored, and lines starting with the exclamation mark character (!) will be treated as comments (ignored). Since blank lines and lines starting with the ! character are ignored by MBBS, now would be a good time to introduce you to an actual MBBS.ACE file. From this point on, the rest of the documentation for ACE will be in the format expected to be found in the MBBS.ACE file (beginning with the - - - CUT - - - line, and ending with the - - - CUT - - - line. Most of the following are comments): ! - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT ! To use MBBS automated commands, you need to create an MBBS command ! file. To accomplish this, you'll need a text editor to create the file ! ! The file should have a name of MBBS.ACE (where ACE is an ! acronym for Automatic Command Execution). The MBBS.ACE file should be ! placed in your PROGRAM directory (the same directory as MBBS.EXE ! resides in). ! Here is the Syntax of an MBBS ACE command: ! CCCCCCC,HH:MM,SSSSSSSSSSSS[,wwww] ! ^ ^ ^ ! | | | ! | | | ! | | |_Command (see below) ! | | ! | |_Time (hh:mm) in 24-hour format (range is 00:00 to 23:59) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 8-2 Magnum's ACE (Automatic Command Execution) Event Handler ! | ! |_Days applicable (0=Sun,1=Mon,...6=Sat) ie: 12345 applies to Mon-Fri ! Text lines starting with the '!' character are comments (ignored) ! MBBS has a physical limit of 100 command lines. This means that the ! MBBS.ACE file must not contain more than 100 commands. Blank lines and ! comments (lines starting with the ! character) are not commands and ! are not counted in the 100 command limit. "Immediate Commands" ! (commands starting with the * character described later) are not ! counted in the 100 command limit either. ! Description of Command: ! The Command SSSSSSSSSSSS can be any Magnum MBBS command just as you'd ! enter on the MBBS command line beginning with the node# or *, OR it ! can be any enclosed in double quotes (" ") if it's a command you wish ! to have OS/2 run instead. If you're using OS/2 commands (in double ! quotes), an additional parameter must follow - WAIT, NOWAIT or DETACH. ! Please realize the consequences of the WAIT parameter: MBBS comes to ! a grinding HALT (won't answer phone, won't accept commands, etc) until ! the process it's WAITing for finishes. With the NOWAIT or DETACH ! parm, the process runs in the background while MBBS continues to run. ! If the process you're starting (in double quotes) writes to ! stdout/stderr (the screen/console), you should redirect it's output to ! the nul device, or to files (redirection is accomplished with the < ! character and the > characters. Example MBBS commands will follow ! later. ! NOTE: MBBS.EXE can read (and store) a maximum of 100 ACE commands. ! With the Alternate Syntax described below (immediate execution ! rather than stored for later execution), immediate ACE commands ! are NOT counted as part of the 100 maximum limit because they ! are executed immediately (as soon as they're read) and then ! discarded (not stored). Also note that the MBBS command (entered ! manually at the "Command ==> " prompt) of "* ACE INIT" will ! re-read the MBBS.ACE command file, overwriting all previously ! stored ACE commands with the ACE commands just read with one ! exception - Immediate commands (those starting with the * char) ! will be ignored - immediate commands will ONLY be processed when ! the MBBS program is initially started. This insures that dual ! copies of the same program(s) are not running unintentionally. ! Also, another MBBS command (entered manually at the ! "Command ==> " prompt) of "* SSSSSSS,wwww" has the same syntax ! as the ACE "immediate" command except that no comma follows ! the * char. ! ! ! Alternate Syntax: ! ! *,SSSSSSSSSS[,wwww] ! ! When used this way, the command executes immediately. When MBBS.EXE MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Magnum's ACE (Automatic Command Execution) Event Handler Page 8-3 ! starts, it reads the commands in the MBBS.ACE file, when a command ! starts with the * character, it is executed immediately! ! ! Internal MBBS commands may be entered exactly as you'd enter them at ! the MBBS command prompt (Command ==> ). External commands - ! programs, .CMD files, or any other command you'd type at the OS/2 ! command line are to be enclosed within double quotes immediately ! followed by a comma (,) and one of the keywords: WAIT, NOWAIT or ! DETACH, where these keywords are defined as: ! ! WAIT - MBBS stops what it's doing and starts the external command ! or program. MBBS will NOT resume until the external ! command finishes. Programs started in this fashion may ! use the console for input/output operations (stdin, ! stdout, stderr). ! ! NOWAIT - MBBS starts the external command or program and ! immediately resumes normal BBS operation while the ! external command or program executes concurrently. NOTE: ! Programs started in this fashion must NOT perform any ! console input/output operations. You may still run ! programs that use console input/output operations by ! redirecting their output to the NUL device, and ! redirecting their input to a file. For example, the ! command: "mbbsexec.exe 1>nul 2>nul" redirects all program ! output to the NUL device (a dummy file). For those of you ! unfamiliar with the redirection of output in this fashion, ! OS/2 predifines the first three file handles of any ! program as 0 (stdin), 1 (stdout), and 2 (stderr). By ! rerouting output with the statements "1>nul" and "2>nul", ! you ensure that both stdout and stderr are rerouted to ! the NUL device. Unlike DOS where ">nul" redirected both ! stdout and stderr to the NUL device, the same ">nul" ! statement in OS/2 only redirects stdout to the NUL device. ! It is important that NO output be written to the screen ! when a program is started with the NOWAIT option, and that ! no input is expected from the keyboard. ! ! DETACH - Similar to the NOWAIT option above, but with the following ! exceptions: The program will be started as a detached ! process which runs in the background, and concurrently ! with other processes in the system. Since the program is ! running as a detached process, it will continue to run ! until it finishes, even if MBBS.EXE is terminated for any ! reason. Console I/O operations are permitted ONLY via ! POPUP windows. ! !-------------------------- ! ! On Startup run program abc.exe and xyz.exe, make Node2 "announce only" ! !-------------------------- MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 8-4 Magnum's ACE (Automatic Command Execution) Event Handler *,"abc.exe 1>nul 2>nul",wait *,"xyz.exe 1>nul 2>nul",detach *,2 announce !-------------------------- ! ! On Mon thru Fri, Shutdown Node3 at 09:00 and - Activate again at 17:00 ! !-------------------------- 12345,08:00,3 shutdown 09:00 12345,17:00,3 Active !-------------------------- ! ! Prepare for System Maintenance at 02:00 every morning ! ! Note that node 4 (console) is left active, otherwise, if all nodes ! were shutdown, MBBS would terminate. ! ! Note that 02:01 is supplied for the time to run mbbsexec.exe, and for ! the commands following it to reactivate nodes 1-3. Even if ! mbbsexec.exe takes 20 minutes to complete, all commands scheduled for ! 02:01 will be processed in order. Since the WAIT parameter is ! specified, the reactivation of nodes 1-3 will not take place until ! mbbsexec.exe finsihes. It is also important to know that had the ! reactivation commands been scheduled for 02:02 (or 02:05) for example, ! and mbbsexec.exe took 10 minutes to complete, the time would be 02:10 ! upon completion and any commands scheduled from 02:01 to 02:09 ! inclusive would not be processed. Therefore, whenever you execute a ! program with the WAIT parameter, you should know how long the program ! will take to complete for obvious reasons. However, by supplying the ! reactivation commands (ie: 0123456,02:01,1 active) as in the sample ! below with the same time (02:01) as the program, you insure that the ! commands will be processed upon completion of the mbbsexec.exe ! program. The exception to this is any command(s) following the ! "shutdown" ace command. Note below how commands following "shutdown" ! are issued AFTER the scheduled shutdown time. ! !-------------------------- 0123456,01:00,1 shutdown 02:00 0123456,01:00,2 shutdown 02:00 0123456,01:00,3 shutdown 02:00 0123456,02:01,"mbbsexec.exe maintain",WAIT 0123456,02:01,1 active 0123456,02:01,2 active 0123456,02:01,3 active !--------------------------------------------------------------------- ! - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Magnum's ACE (Automatic Command Execution) Event Handler Page 8-5 This has been an explanation of the creation, syntax and usage of an MBBS.ACE command file. When you run the MBBS.EXE program, the MBBS.ACE file will be read and checked for syntax errors. ACE commands will be stored (queued) for later execution. Immediate commands will be processed right away. All executed ACE commands are logged to file ACE.LOG (in your PROGRAM directory) at the time of execution. NOTE: ANY command that can be entered at the MBBS.EXE's "Command => " prompt can be an ACE command (see the chapter "Magnum's Sysop Console"). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 8-6 Magnum's ACE (Automatic Command Execution) Event Handler Advanced ACE Usage In addition to the syntax covered earlier, you also have the capability to queue a command based on the date of the month! For example, if you wanted to queue (store) an ACE command to be executed on the 15th day of each month (at 02:01), your ACE command might look like this: -15,02:01,"maintain.cmd",wait or suppose a command is to be executed on the 1st of each month (at 01:00): -1,01:00,2 shutdown 02:00 the secret is the - character (the minus sign) in column 1 of the queued command. Keep in mind that February has 28 (or 29) days, therefore, if you want a command to execute on the 30th of each month, it will never execute in February! Likewise, if you specify for a command to be executed on the 31st of each month, it will never execute during months containing less than 31 days! Additionally, you also have the capability to queue a command based on a specific date! For example, if you wanted to queue (store) an ACE command to be executed on July 4, 1994 at 02:01, your ACE command might look like this: 07/04/1994,02:01,"maintain.cmd",wait or 04.07.1994,02:01,2 shutdown 02:00 Note that the date can be either in European or U.S. date format. Leading 0's for month or day are not necessary (ie: 7/4/1994). The year (if provided) can be 1 to 4 digits. The year is optional, and if omitted (ie: 7/4 or 4.7 or 07/04 or 04.07), then the command will execute on July 4th EVERY year. If a 1-digit year is provided, the current decade will be used (ie: if the current year is 1993 and you provide 5 for the year, then 1995 will be used); if a 2-digit year is provided, the current century will be used; if a 3-digit year is provided, the current millenium will be used. A 4-digit year will be accepted as is. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-1 MBBSEXEC Utility for "Magnum OS/2 BBS" (C)Copyright 1989,1993 Gilmore Systems - All rights reserved This chapter explains the use of MBBSEXEC.EXE, a Sysop utility program for the management of the Magnum BBS database files USER.DAT, USER.KEY, FILE.DAT, MSG.DAT, RJE.DAT, and UTILIZ.DAT. As a Sysop of a Magnum OS/2 BBS, you have probably discovered a great deal of routine things which you'd like to do with the contents of the records and fields within Magnum's databases. Some examples of these routine tasks which immediately come to mind are: - Delete all users whose last call was 180 days ago or greater - Delete all messages older than 90 days - Delete all files older than 365 days - Upgrade all users who've entered 2 or more public messages - Lower the security level of all users who's memodate has expired - Add an expiration date to all messages or files in a specific area - Increase time limit for users who've uploaded 10 or more files - Delete all files having less than 10 downloads in the past 60 days - List all users with an interest in music (or whatever you choose) - Upgrade Users ONLINE based on the results of a questionairre. - Generate Form Letters and/or Mailing Labels to all users matching specific criteria. - Generate reports showing what percentage of your users fall into specific criteria. This is just a very small example of what can be done with the MBBSEXEC program. There is virtually no limit on what you can do - MBBSEXEC simplifies all of your database management needs. MBBSEXEC is an interpreter (like BASIC) which interprets your programs (.MEX files) and performs the programming instructions within. This powerful interpreter is similar to the C programming language but has slightly stricter rules as far as opening and closing braces ( '{' and '}' characters). MBBSEXEC will be covered in two sections of this chapter. In the first section we'll start with a presentation of MBBSEXEC as a 'simple' programming language. This will provide those with little to no programming experience the information they need in order to write their own .MEX programs. By using MBBSEXEC as a 'simple' programming language, all of your Magnum database management needs can be taken care of. In the second section (the 'Advanced' section), we'll present advanced techniques oriented more towards those with programming experience, yet keeping it simple enough to understand (where possible) such that those new to programming can apply the advanced features to their .MEX programs. An MBBSEXEC program consists of a regular ASCII text file which you create with your favorite text editor. When you create an MBBSEXEC program with your text editor, you'll need to save it with a filename extension of ".MEX" (MbbsEXecutable). MBBSEXEC reads your .MEX file and processes the statements within. In other words, if you've created a MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-2 The MBBSEXEC Sysop Maintenance Utility Program text file to list all users with an interest in music, your MBBSEXEC input file would probably have a name of MUSIC.MEX, and you'd start MBBSEXEC with: MBBSEXEC MUSIC MBBSEXEC assumes an extension of .MEX although if you supply your own extension MBBSEXEC will use that filename instead. Following is an example of an MBBSEXEC program which will compile a list of all users who've listed MUSIC as one of their interests: ! ! List all users with an interest in MUSIC ! #CONFIG_FILE: E:\GS\MAGNUM\MBBSINIT.1 #LOG_FILE: MUSIC.LOG #DATABASE: USER #START if(@i ~ "music") { log("Interests: ",@i) log("ID: /",@id) log("lastname: ",@lastname) log("firstname: ",@firstname) log("middlename: ",@middlename) log("---------------------------") } #STOP Note in the above MBBSEXEC program, the very first thing you see is the exclamation mark (!) character. Any lines starting with the '!' character will be ignored - it merely serves as a comment line. The exclamation mark (!) always indicates the start of a comment - the comment always ends at the physical end of the text line the ! appeared in. There are only three exceptions as to when the ! character does NOT start a comment: - If it appears within double quotes ("...!..."). - If it is immediately followed by the "=" character ( != ). - If it is immediately preceeded & followed by single quotes ( '!' ). Next, three (3) '#' statements follow. The first is "#CONFIG_FILE:" which tells MBBSEXEC which database to work on by giving it the full filespec (path & filename) of the mbbs initialization file for Node01 (note the filename extension tells MBBSEXEC which node to work on). MBBSEXEC obtains all of it's information such as database names from this file. Usually MBBSINIT.1 is all that's needed since most BBS sysops running mulitple nodes are pointing the database files to the same SESION DIRectory. In the event that the Sysop is running 2 or 3 unique BBSes (different SESSION DIRectories and thus different user, MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-3 file, rje and message databases), you would need to change the #CONFIG_FILE statement to point to MBBSINIT.2 or MBBSINIT.3 so that those databases will also be changed. The second statement is the "#LOG_FILE: " statement which gives MBBSEXEC the filename (or device name such as "prn") in which to write statements to. The 3rd one is the "#DATABASE: " statement which tells MBBSEXEC which database to work on (can be USER, MSG, FILE, RJE or UTILIZ) - in this case, it's USER. Next comes the actual MBBSEXEC program which starts with the "#START" statement and ends with the "#STOP" statement - all text falling within the "#START" and "#STOP" statements are code or instructional statements. Examining the above code, we notice that the first code statement is: if(@i ~ "music") { Breaking down this statement, we note that the syntax of an IF statement is: if(expression) { where "expression" is some sort of comparison operation. In this case, the '~' character separating the "@i" from "music" is an operation which checks to see if string2 is contained within string1. In this case, string1 is "@i" which is MBBSEXEC's notation for "USER INTERESTS". Should the string "music" appear within string1 (USER INTERESTS), the result will be TRUE, otherwise FALSE. NOTE THAT THE OPENING BRACE ( { ) MUST APPEAR ON THE SAME LINE AS THE "IF(expression)" statement. In other words: if(expression) this is INCORRECT { . . } if(expression) { this is correct . . } If the "expression" is TRUE, then MBBSEXEC will perform the statements enclosed between the starting and ending braces ( { and } ). If the "expression" is FALSE, then MBBSEXEC will skip to the first statement following the ending brace ( } ). Please note that the ending brace must be on a line by itself, while the beginning brace must be the first nonspace character appearing after an "if(expression)" statement. Note that within the comparison expression, case (upper/lowercase) is not important. "music", "Music", "MUSIC", "MuSic" are all identical as far as MBBSEXEC is concerned. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-4 The MBBSEXEC Sysop Maintenance Utility Program Within the braces in the above example is a series of "log" statements. A "log" statement merely writes output to the "LOG" file you specificed in the "#LOG_FILE: " statement. The basic syntax of a log statement is: log("quoted string",@field) or log("quoted string") The "quoted string" parameter gets written to the log file, and the @field writes the current value of @field to the log file. In the former, @field can be any of the predefined user fields (we'll present a list of predefined field names later). MBBSEXEC will perform the statements between the #START and #STOP statements once for EACH record within the USER database. It will scan every @I field (user interests) for the word "MUSIC", and if the comparison is TRUE, MBBSEXEC will perform all of the statements within the { and } block. The list might look something like this: Interests: FISHING SWIMMING MUSIC CHESS ID: /158 lastname: SMITH firstname: JOHN middlename: S --------------------------- Interests: COMPUTERS MUSIC MIDI ID: /202 lastname: JOHNSON firstname: ALFRED middelname: E --------------------------- Interests: OS/2 MUSIC CARS BOATS ID: /303 lastname: DUNN firstname: JULIE middlename: SARAH --------------------------- This example only made a list of users with a specific interest. MBBSEXEC is also capable of modifying user fields as we'll see in a moment. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-5 MBBSEXEC Field Names MBBSEXEC incorporates predefined field names for accessing the individual fields within the databases. When you access the Sysop menu from within Magnum BBS, you'll notice that most of the field names for the User Database area will usually be the same names as those used by the MBBSEXEC program. The '@' character precedes all field names within the MBBSEXEC program. MBBSEXEC supports the USER.DAT and USER.KEY databases, the FILE.DAT database, the MSG.DAT database, the RJE.DAT and the UTILIZ.DAT database. NOTE: IT IS STRONGLY RECOMMENDED THAT YOU BACK UP YOUR *.DAT AND *.KEY FILES BEFORE RUNNING THE MBBSEXEC PROGRAM. THIS WAY YOU'LL BE ABLE TO RESTORE THE DATABASES IN THE EVENT OF AN UNEXPECTED ALTERATION TO THE DATABASES. IMPORTANT: IF AN ERROR OCCURS DURING PROCESSING YOUR .MEX FILE (SYNTAX OR OTHERWISE), AND A LINE NUMBER INDICATING WHICH LINE THE ERROR OCCURED, MBBSEXEC CREATES A FILE WITH AN EXTENSION OF .SNP (SNAPSHOT) - THIS .SNP FILE IS THE FILE IT IS REFERRING TO - NOT YOUR ORIGINAL .MEX FILE!!! IF YOUR .MEX FILE IS CALLED MUSIC.MEX, THE REFERENCE TO THE ERROR IS IN THE LINE NUMBER SPECIFIED BY THE ERROR MESSAGE IN FILE MUSIC.SNP Before beginning, we'll present the allowable field names for the 5 databases which MBBSEXEC will accept. Before presenting the list, we must point out that there is one fieldname used internally by MBBSEXEC which is not a part of the database fields. This fieldname is @TODAY which, when encountered in an MBBSEXEC program statement, is replaced with the current date. This allows such statements as: if(@lastcall < @today - 90) { @deleted = TRUE log("Deleted ID: /",@id) } The above statement would delete all users who's last call to the bbs was greater than 90 days ago from today. All MBBSEXEC fieldnames are case insensitive meaning that you can type these fieldnames in uppercase, lowercase or any combination. NOTE: All DATE fields are in U.S. format (MM/DD/YYYY) and must be 10 characters in length. Even if you're using a European version of Magnum, the internal storage of dates are in U.S. format! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-6 The MBBSEXEC Sysop Maintenance Utility Program Field Names for the USER Database Following is a list of the fieldnames and their meanings. Note that in column 1, a lowercase letter appears which indicates what type of field it is. This lowercase letter is one of: s=string, n=numeric, c=character, b=boolean. You'll need to know this information later on when you write your MBBSEXEC programs. Here is the USER fieldname list: s @LASTNAME - User's Last Name s @FIRSTNAME - User's First Name s @MIDDLENAME - User's Middle Name n @ID - User's ID number (NOTE: number only, no '/' char) s @STREET1 - User's Company Name or User's Handle (alias name) s @STREET2 - User's Street Address s @CITY - User's City s @STATE - User's State or Province s @ZIP - User's Zip Code or other Zone Info s @COUNTRY - User's Country s @FIRSTCALL - Date User First Called the BBS (MM/DD/YYYY) s @LASTCALL - Date User Last Called the BBS (MM/DD/YYYY) s @TIMELAST - Time User Last Called (HH:MM in 24-hr format) s @PASSWORD - User's Password s @DOB - User's Date of Birth (MM/DD/YYYY) s @PHONE1 - User's Home Phone# s @PHONE2 - User's Company Phone# s @CPUTYPE - User's Computer Type [can be overridden with a sysop-defined field. See CPUTYPE_OVERRIDE in Ch 1. s @CONFERENCES - User's Conferences allowed (ie: "abefh") s @MEMODATE1 - User's Memodate #1 s @MEMODATE2 - User's Memodate #2 b @PRIVMSG - Is user allowed to enter Private Messages? b @DELMSG - Is user allowed to delete messages? s @SYSOP_COMMENT - Sysop's Comment about user c @XFERTYPE - User's default file xfer protocol (X,C,1,Y,G,Z,N) c @PERIODTYPE - User's Period Type (D,W,M,Y) b @EXPERT - Expert mode on? b @LOCKED_OUT - Is user locked out? b @COLOR - Is user using ANSI color? b @DISPLAY_MORE - Does user want the "- - More - -" prompt? b @ERASE_MORE - Does user want the "- - More - -" prompt erased? b @HOTKEYS - Is user using single-keystroke commands? n @LINES_PAGE - User's number of lines per page n @LEVEL - User's security level n @UPLOADS - Number of uploads user performed n @DOWNLOADS - Number of downloads user performed n @CPS - User's adjusted Characters Per Second transfer rate n @UDRATIO - User's Upload/Download ratio n @TTL_CALLS - User's total number of calls n @REMAINING - User's time remaining for the last call n @REMAINING_PERIOD - User's time remaining for the period n @K_UL - Kbytes User performed in Uploads n @K_DL - Kbytes User performed in Downloads n @PERIOD_DL - User's downloads this period n @PERIOD_K_DL - User's Kbyte downloads this period n @DL_THIS_PERIOD - Downloads user performed this period MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-7 Field Names for the USER Database n @K_DL_THIS_PERIOD - Kbytes in downloads user performed this period n @DAILY_TIME - Daily Time allowed on system n @DAILY_DL - Daily downloads User is allowed n @DAILY_K_DL - Daily Kbyte downloads User is allowed b @PRIVACY - Is user's Privacy switch on? s @FILE_U_AREAS - File upload areas allowed s @FILE_D_AREAS - File download areas allowed s @FILE_L_AREAS - File list areas allowed s @MSG_R_AREAS - Message Read areas allowed s @MSG_W_AREAS - Message Write areas allowed s @MSG_L_AREAS - Message List areas allowed s @MILC_CMDS - Display commands allowed s @I - User's interests c @COMPRESS - User's compression type (A,Z) n @PUBLM - Number of public messages entered by user n @PRIVM - Number of private messages entered by user b @DELETED - Is this user deleted? c @DATEFORMAT - User's Date Format (U=US, E=Europe) b @SUB_FILEDEL - Subtract upload credit when a user deletes a file? s @FREE_DL_AREAS - Specify the area(s) (A-Z) which a user can download from without being counted toward their UL/DL ratio n @FREE_DOWNLOADS - The number of FREE downloads the user has performed n @RJEJOBS - The number of RJE jobs the user submitted. n @SENDNULLS - Number of Nulls to send after CR/LF (usually 0) can range from 0 to 255. c @FILELIST_PREF - The user's FileList preference (C=Chronological order, R=Reverse Chronological Order). No defaults. b @REUSE - Y/N or TRUE/FALSE to indicate that this ID (record) can or cannot be reused if deleted. Note that in order for this to be reused, the REUSE_DEL keyword in your STARTUP.n file(s) must also be set to Y. n @MSGGROUP - For those using the extended MsgBase module, accesses the user's message group field. n @FILEGROUP - For those using the extended FileBase module, access the user's file group field. c @TYPE - Magnum supports two kinds of user accounts. USER and MAIL. This field holds either U for USER or M for MAIL. n @FILEBASE - The LAST FileBase the User was in, or the default FileBase to jump to the next time the user logs on. n @MSGBASE - The LAST MsgBase the User was in, or the default MsgBase to jump to the next time the user logs on. b @RMAIL - Y/N or TRUE/FALSE to indicate that this user can or cannot use the remote mail system. If TRUE, the user can enter a message to another user on another Magnum system supported by the Sysop. If FALSE, the user cannot enter or reply to remote mail messages. c @EDITOR_PREF - Refers to the user's preference of L (Line editor), or A (Ansi editor), or N (None). b @SHOW_EXTDESC - Y/N or TRUE/FALSE to indicate whether the user has chosen to include extended (long) file descriptions during any file listings. b @USING_HANDLE - Y/N or TRUE/FALSE to indicate whether this user is MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-8 The MBBSEXEC Sysop Maintenance Utility Program Field Names for the USER Database using a handle (alias name). Note that if FALSE or N, the @STREET1 field holds their company name (if used), otherwise if TRUE or Y, its their handle. b @OUTSIDE_MAIL - Y/N or TRUE/FALSE to indicate whether this user has access to "outside mail". s @IA - The user's Internet E-mail Address. Note: this string does NOT include the domain name (ie: the @company.com part). Example: sysop is valid, sysop@company.com is not. Note that field types (s,n,c,b) indicate what type field is being described by the fieldnames. For type 'b' (boolean), it will hold one of two things - TRUE or FALSE (or Y or N, or 1 or 0). We suggest using the words TRUE or FALSE for these fields. For example: @PRIVACY = FALSE The n (numeric) fields hold digits only. For example: @UDRATIO = 20 The c (character) fields hold a single character and must be within single quotes when comparing or assigning. For example: if(@compress == 'A') { @COMPRESS = 'Z' } Finally, the s (string) fields holds a string of characters and must be within double quotes when comparing or assigning. For example: if(@firstname == "Richard") { @firstname = "Rick" } Note the 1st parameter of all comparisons must be a valid fieldname. The 2nd parameter can be a fieldname or something you choose to compare. This covers the fieldnames for the USER databases. Next, we'll cover the FILE, MESSAGE, RJE and UTILIZ databases, then continue with the syntax and construction of an MBBSEXEC program. IMPORTANT: See the section entitled "Date Fields are Special Cases" MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-9 Field Names for the MSG Database b @DELETED - Is this message deleted? c @CONF - Conference area (A-Z) of message b @PRIVATE - Is this a private message? b @RECEIVED - Has the message been received by addressee? n @FROM - ID of who wrote the message (-1 if from Magnum) n @TO - ID of who the message is to (-1 if for ALL) n @NUM - ID of original addresse (if CC or Forward) n @TIMESREAD - Number of times message was read s @SUBJECT - Message Subject s @DATE - Date of Message (MM/DD/YYYY) s @TIME - Time of Message (HH:MM in 24-hour format) s @EXPDATE - Expiration date of message (MM/DD/YYYY) b @CC - Is this a carbon copy? b @FORWARD - Is this a Forwarded message? b @RECEIPT - Is a receipt wanted for this message? b @REPLIES - Are their any replies to this message? b @ISREPLY - Is this message a reply to another message? s @RCVDATE - Date message was received by addressee (MM/DD/YYYY) s @RCVTIME - Time message was received by addressee (MM/DD/YYYY) s @FILENAME - Ref# or Filename (excluding pathname) of message n @MSGBASE - Indicates MessageBase of message (0-255) (will always be 0 if you don't have the optional extended messagebase module). n @FROM_PSERNUM - Parent Serial# of Sending BBS n @TO_PSERNUM - Parent Serial# of Target BBS b @SENT - Sent (TRUE/FALSE) [if to a different BBS] s @FROM_USERNAME - Full name (string) of originating user s @TO_USERNAME - Full name (string) of addressee s @FROM_FILENAME - Originating System's Filename (REF#) n @FROM_MSGBASE - Originating System's MsgBase (0-255) c @MSGMILC - The MILC character used for this message. NOTE: This field is meant to be used when the serial# of the destination system is not the same as the serial# of the sending system. b @ECHO - Y/N or TRUE/FALSE to indicate that this message is echoable to other systems on the mail network. If not, the message is sent as store/forward only. NOTE: This field is ONLY valid if the serial# of the destination system is not the same as the serial# of the sending system. n @RECNUM - The recorded (and not necessarily the actual) record number for the current record. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-10 The MBBSEXEC Sysop Maintenance Utility Program Field Names for the FILE Database b @DELETED - Is this file deleted? c @AREA - Area file is in (A-Z) b @PRIVATE - Is this a private (password protected) file? c @UL_METHOD - Upload method (X,C,1,Y,G,Z) s @NAME - Name of file (filename.ext) s @PASSWORD - Password of file (if @private == TRUE) s @DATE - Date file was uploaded (MM/DD/YYYY) s @TIME - Time file was uploaded (HH:MM in 24-hour format) s @EXPDATE - Expiration date of file (MM/DD/YYYY) s @BRIEF - Brief explanation of file (string of 76 chars) s @DATELAST - Date Last accessed (MM/DD/YYYY) n @WHO - ID of uploader b @DESFILE - Is a description file available? n @SIZE - Size of file n @DL - Number of downloads n @FILEBASE - Indicates FileBase (0-255) (will always be 0 if you don't have the optional extended filebase module). c @CDROM - If alphabetic indicates the file is on a cd-rom or other drive described by a directory which is external to the file database. n @PATHNUM - Indicates which path number to use in the external pathname file (if @CDROM is alphabetic). n @RECNUM - The recorded (and not necessarily the actual) record number for the current record. NOTE: The @CDROM and @PATHNUM variables are to be used for informational purposes only (unless you REALLY know what you're doing)! Do not mess with these (you probably won't have a use for these two variables anyway). The following is an example .MEX program (MISMATCH.MEX) which checks for and corrects recorded vs physical record numbers: #CONFIG_FILE: mbbsinit.1 #LOG_FILE: mismatch.log #DATABASE: FILE* #START if(@thisrec != @recnum) { log("Recorded: ",@recnum," Actual: ",@thisrec) @recnum = @thisrec } #STOP You can change #DATABASE: FILE* to #DATABASE: MSG* to process the MsgBases instead of the FileBases. The * character tells MBBSEXEC to process ALL FileBases (or ALL MsgBases) for those with the Extended FileBase and/or Extended MsgBase modules. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-11 Field Names for the FILE Database MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-12 The MBBSEXEC Sysop Maintenance Utility Program Field Names for the RJE Database b @DELETED - Is this record deleted? b @STATUS - Is this RJE Job completed? s @NAME - RJE Jobname Magnum assigned to this Job s @STARTDATE - Date Job started (MM/DD/YYYY) s @STOPDATE - Date Job ended (MM/DD/YYYY) s @PGMNAME - Name of program started s @PARMS - Parms (arguments) passed to program n @USERID - User ID of User that started this Job n @STARTTIME - Time started (seconds from midnight of @STARTDATE) n @STOPTIME - Time stopped (seconds from midnight of @STOPDATE) n @SECONDS - Total run time of job in elapsed seconds n @PRTYCLASS - Priority class of Job when started n @PRTYLEVEL - Priority level of Job when started n @PID - Process IDentification of Job NOTES: - The keywords @STOPDATE, @STOPTIME and @SECONDS have no meaning if @STATUS is FALSE (job is still running). - The keyword @PID has no meaning if @STATUS is TRUE (job is completed). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-13 Field Names for the UTILIZ Database n @NODE - Node number ** See NOTE #1 below s @STARTDATE - Session started (MM/DD/YYYY) s @STOPDATE - Session ended (MM/DD/YYYY) n @STARTTIME - Start time in seconds from midnight n @STOPTIME - Stop time in seconds from midnight n @IDNUM - User idnum for this session n @BAUDRATE - User's baud rate ** See NOTE #2 below n @LEVEL - User's security level n @MSGS_READ - # msgs read this session n @MSGS_WRITTEN - # msgs written this session n @FILES_UL - # files uploaded this session n @FILES_DL - # files downloaded this session n @RJEJOBS - # RJE jobs started this session n @SERIALNUM - Serial# of session (not parent#) n @TTLTIME - Ttl time of session (seconds) ** See NOTE #3 below NOTE #1: When processing the UTILIZ database, if the @NODE value is a negative number, it indicates the session was terminated due to dropped carrier. If the @NODE value is negative, simply multiply by -1 to obtain the correct node number. If the @NODE value is negative (dropped carrier), information in the record may be worthless if the drop of carrier took place prior to the user actually logging on. To find out if the user actually logged on, the @BAUDRATE value should be non-zero. If the @BAUDRATE value is zero, this record is to be disregarded. NOTE #2: When processing the UTILIZ database, if the @BAUDRATE value is a negative number, it indicates the connection was established with modem error correction (ie: MNP, LAP, etc). If the @BAUDRATE value is negative, simply multiply by -1 to obtain the correct baudrate. If the @BAUDRATE value is zero (0), the entire record is to be discarded (ignored) because the session ended due to dropped carrier prior to the user actually logging on. NOTE #3: When processing the UTILIZ database, the @TTLTIME variable is not part of the database, but is derived by MBBSEXEC.EXE by taking into consideration the @STARTDATE, @STARTTIME, @STOPDATE and @STOPTIME parameters. @TTLTIME is expressed as the total number of seconds the user was online. @TTLTIME is a "read-only" variable. You cannot use this variable to assign a value to (ie: must not appear on the left side of an = sign). Please note that the UTILIZ.DAT database will not exist unless the TRACK_UTILIZATION parm in your STARTUP.x file(s) is set to Y. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-14 The MBBSEXEC Sysop Maintenance Utility Program Syntax and Construction of an MBBSEXEC program An MBBSEXEC program consists of an ASCII text file containing MBBSEXEC program statements. The physical limitations of the file are: - Each text line can be up to 120 characters in length - Each text line must be terminated by a CR/LF pair (automatic with most text editors) - The entire file must not exceed 64,000 bytes (file size). We've seen an example of a small MBBSEXEC program earlier, but we'll review the basic skeleton here again: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: MUSIC.LOG #DATABASE: USER #START . . . ! This is a comment . . . #STOP The #CONFIG_FILE: statement tells MBBSEXEC the name of the initialization file used by the BBS program (MBBS.EXE). The #LOG_FILE: statement tells MBBSEXEC what file to write "log" statements to. The #DATABASE: statement tells MBBSEXEC which database to work on (USER, MSG, FILE, RJE or UTILIZ) - this is important because you'll also note that some of the fieldnames for the 5 databases are identical - it is the #DATABASE: statement which makes the distinction. NOTE: For those using the Magnum 'Extended MessageBase' or 'Extended FileBase' modules, you can specify which MessageBase or FileBase file to process (not to be confused with the @MSGBASE field or @FILEBASE fields above) by specifying the #DATABASE statement as follows (via examples): #DATABASE: MSG defaults to main Message Database #DATABASE: MSG5 uses Message Database 5 #DATABASE: MSG109 uses Message Database 109 #DATABASE: MSG0 same as "#DATABASE: MSG" #DATABASE: FILE same as "#DATABASE: FILE0" #DATABASE: FILE76 uses File Database 76 Be advised that this statement is used only to determine the filespec of the datafile for that message or file base. If you're using MSG.DAT in the session directory for each of your message bases, then MSG and MSG110, for example, are mutually exclusive. If any of the FILE or MSG databases are used for more than one MSG or FILE database, use the @MSGBASE or @FILEBASE keywords MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-15 Syntax and Construction of an MBBSEXEC program (fields) within your .MEX programs to narrow down which file or message base you wish. NOTE: For users of the Extended FileBase or MsgBase modules, you may also use the follwoing #DATABASE statements: #DATABASE: FILE* #DATABASE: MSG* When the asterisk character (*) is used as above (FILE* or MSG*), it tells MBBSEXEC to apply your .MEX program to EVERY FILE and MSG database on the system! This comes in handy for those who do not keep their message and/or file database in a single database file. MBBSEXEC will always start with your main database, then restart with the next, then the next, etc with this method. The #START and #STOP statements tell MBBSEXEC that all statements appearing inbetween are to be executed (carried out) for every record in the database. Note that any statement starting with an exclamation mark (!) is a comment and will be ignored by MBBSEXEC. Comments merely serve as useful notes to yourself. The periods above (.) are not statements but merely for illustrative purposes - these periods (.) would represent actual program statements in an MBBSEXEC program file. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-16 The MBBSEXEC Sysop Maintenance Utility Program The Assignment Statement The Assignment statement is the simplest of all. Basically, an assignment statement places a value you supply into one of the fields. For example, the statement: @memodate1 = "06/30/1990" would assign the string "06/30/1990" to the @memodate1 field of the user database. You'll probably want to have assignment statements execute only if an IF statement is true, otherwise it will be assigned to all users. The above example is an example of string assignment. If the field is a string field, then the assignment part must be enclosed within double quotes. Another example: @file_l_areas = "abchjk" An example of an assignment statement for a character field would be enclosed in single quotes. For example: @compress = 'Z' An example of an assignment statement for a numeric field is probably the simplest of the assignment statements. For exmple: @level = 6 Finally, an assignment statement for a boolean field is either TRUE or FALSE. For example: @color = TRUE Date fields are handled differently - BE SURE TO VIEW THE SECTION ENTITLED "DATE FIELDS ARE SPECIAL CASES"! For any assignment statement, look at the database fieldname earlier in this chapter and note if it's a string, character, numeric or boolean field and follow the assignment rules for that type of field. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-17 Comparison Statements (IF) The Comparison (or IF) statements are somewhat more comprehensive to grasp. If you're experienced in the C programming language it will help you a great deal. Keep in mind the rules you've learned for the 4 kinds of datatypes described earlier (string, numeric, character and boolean). The same rules apply for comparisons (ie: strings to be compared with double-quoted strings, characters to be compared with a single-quoted character, numerics to be compared with digits, and booleans to be compared with TRUE or FALSE). There are 7 kinds of comparators for comparison statements. A comparator tells MBBSEXEC what kind of comparison you wish performed on the two fields being compared. The comparators are: == Test for equality != Test for inequality >= Test for greater than or equal <= Test for less than or equal > Test for greater than < Test for less than ~ Test if string2 is within string1 (string comparisons only) NOTE: The ~ comparator sets the @RESULTCODE (a read-only variable) to 0 if no match, or the starting position of where within string1 the match was found! For example: If @STRING1 contained "a musical instrument", then the following statement would set @RESULTCODE to 3: if(@string1 ~ "music") { . . } The following tests for user id of 177 and deletes the user if matched. if(@id == 177) { @deleted = TRUE } The following example tests for all callers whose last call to the BBS was 90 days ago or more and deletes them if true. if(@lastcall < @today - 90) { @deleted = TRUE } NOTE: Nested IF statements are allowed. See "MBBSEXEC Advanced Features" later in this chapter. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-18 The MBBSEXEC Sysop Maintenance Utility Program Branch Statements (GOTO) There will be times when you wish to test for a certain condition and skip program statements if the condition tests true. Since MBBSEXEC is a simple programming language without AND and OR operators, the GOTO statement can emulate AND and/or OR conditions. The GOTO statement consists of 2 parts: the actual GOTO statement, and a LABEL as the target of a GOTO. The syntax of a GOTO statement is: goto(labelname) The Syntax of a label is: labelname: The two things to remember are that the GOTO itself must be followed by a label name enclosed within parenthesis, and the actual label name must appear elsewhere within the #START and #STOP statements and must end with the colon (:) character. As an example, suppose you want to increase the security level of level 5 users to level 6 only if they've entered 2 or more public messages. The following example demonstrates this: if(@level != 5) { goto(skipit) } if(@publm >= 2) { @level = 6 log("Upgraded from level 5 to 6: /",@ID) log("Lastname: ",@lastname) log("Firstname: ",@firstname) log("# Public Msgs entered: ",@publm) log("-------------------------------") } skipit: In the above example, the first IF statement tests the user level. If it is not a user level of 5, then the IF condition is TRUE and takes the branch to the SKIPIT: label. We want to perform this branch because we want the following statements executed for only level 5 users. If they are a level 5 user, the first IF will test out FALSE and will not take the branch - instead, it will fall through to the next IF statement which tests for the number of public messages entered. If 2 or more public messages are entered, the user's security level is changed to 6 and we write a summary of the change to the log file. The above programming statements show how an AND condition can be emulated by using a couple of IF statements and a GOTO. In a higher level language such as C, the same thing could be accomplished without a GOTO and with only 1 IF statement - ie: if((@level == 5) && (@publm >= 2)) but since this is a simple programming language, we must use the 2 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-19 Branch Statements (GOTO) IF statements in conjunction with a GOTO. For those with programming experience, IF statements can be nested in order to emulate an AND statement: if(@level == 5) { if(@publm >= 2) { @level = 6 log("Upgraded from level 5 to 6: /",@ID) log("Lastname: ",@lastname) log("Firstname: ",@firstname) log("# Public Msgs entered: ",@publm) log("-------------------------------") } } The above example (using nested IF statements) demonstrates a cleaner way of doing things, and eliminates the need for a GOTO statement. An important thing to keep in mind is the testing of a field for NUL (if there's anything in a field). These can all be accomplished by having the second parameter of an IF statement as 0. For example, if you wanted to delete all users whose memodate1 field is older than today, you would first need to test if the memodate1 field had a value in it: if(@memodate1 == 0) { goto(skipit) } if(@memodate1 < @today) { @deleted = TRUE } skipit: All fields pertaining to dates are handled as special cases. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-20 The MBBSEXEC Sysop Maintenance Utility Program Date Fields are Special Cases Date fields are handled differently for comparisons than assignments. As a matter of fact, date fields are handled as numerics during comparison, and as strings during assignments. For example, the statement: if(@lastcall < @today - 90) { . . } is handled internally by treating the @lastcall and @today fields as numerics. This way, MBBSEXEC can perform numeric arithmetic and comparison by first converting date fields to numeric numbers representing number of days since Jan 1, 1980. You needn't concern yourself with this, other than the fact that you need to know that dates are handled as numerics for comparison purposes. When assigning something to a date field, the assignment is handled as a double quoted string as expected: @memodate1 = "06/01/1990" The @memodate1 and @memodate2 fields can also accept the @today field + or - a value. For example, the following might be used to set expiration dates of 6 and 12 months for a subscription BBS: @memodate1 = @today + 183 @memodate2 = @today + 366 Another .MEX file might run as a daily maintenance program which checks these @memodate fields for expiration and act accordingly. It is important to remember the date rules. In other words, you can't compare a date field against a quoted string, but you can compare it to something like @today-90 and you can assign a string such as "06/01/1990" to a date field (and can use the exception of assigning with the @today +/- n). REMINDER: ALL DATES ARE STORED AND ENTERED IN U.S. DATE FORMAT!! DO NOT USE EUROPEAN DATE FORMAT WHEN WRITING YOUR .MEX FILES!! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-21 Mathematics Finally, mathematics can be performed within MBBSEXEC program statements as we've seen with the "@today - 90" example of subtraction. The mathematical operators which are supported by MBBSEXEC are: + Addition - Subtraction / Division * Multiplication % Modulus For those unfamiliar with Modulus, it simply means "remainder". For example, 5 divided by 3 (or 5/3) is 1, while 5 modulus 3 (or 5%3) is 2. In other words, 3 goes into 5 one time (division) with a remainder of two (modulus). You may use arithmetic on any numeric field for assignment, or date field for comparison. For example, to add 10 minutes to a user's daily time would be accomplished with: @daily_time = @daily_time + 10 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-22 The MBBSEXEC Sysop Maintenance Utility Program Processing a Single User Instead of the Entire Database Instead of looping through every user in the USER database, there may be times you wish to process only a single user instead. With what you've learned above, you know that we can check for a certain user id and process statements only if that id matches. If all you wanted to do was process a single matching user id, this method would be a tremendous waste of time since MBBSEXEC would loop through every record in the database, only to process changes for one user. This Section explains a feature built into MBBSEXEC which will accomplish just that. Single-user processing is currently limited only to the USER database (USER.DAT and USER.KEY files), and must be the FIRST database processed (won't work if you've processed FILE or MSG database first in the same .MEX file). There are 2 ways of accomplishing single-user processing. The first way is to provide the user's ID number on the #START line. For example: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: PRN #DATABASE: USER #START 212 . . . #STOP The above would process the user with user id 212 only. The second method is to supply the user id to process on the program command line: MBBSEXEC UPDT 212 which would process the UPDT.MEX file for user id 212 only. This method works as though you had a statement of: #START 212 in your .MEX file. Remember, single-user processing only works on the very first #START statement encountered in the .MEX file, and it must be part of the USER database - the FILE, MSG, RJE and UTILIZ databases ignore this parameter. One great example of single-user processing would be the following: Suppose you ran a subscription BBS and wanted to update users who've subscribed to a higher security level with more capabilities on the system. Just as an example, your .MEX file might look something like this: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: PRN MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-23 Processing a Single User Instead of the Entire Database #DATABASE: USER #START @level = 50 @msg_r_areas = "abcdefghijklmwxz" @msg_w_areas = "abcdefghijklm" @msg_l_areas = "abcdefghijklmz" @file_u_areas = "mn" @file_d_areas = "abcdefghijklmnz" @file_l_areas = "abcdefghijklmnz" @daily_time = 90 @periodtype = 'w' @udratio = 0 #STOP The above .MEX file would normally loop through the entire USER database and change EVERY user to the above criteria since there are no IF or GOTO statements in this particular file. Assuming the above statements are stored in filename LVL50.MEX, the following invocation of MBBSEXEC would in fact, change EVERY user in the USER database to the above criteria: MBBSEXEC LVL50 If the #START statement in the LVL50.MEX file had a number after it, only the user id matching that number would be processed. However, the following invocation of MBBSEXEC would change only one user, user 321 for example: MBBSEXEC LVL50 321 Note that by supplying a USER id on the program command line, it will override a hard-coded user id (ie: one that's part of a #START statement). With this crude example, you can see the power of having separate .MEX files for different security levels. To change anyone's security level at anytime, including all the fields you've associated with a particular security level, simply adapt the above method to your particular needs. This technique can also be used in conjunction with Magnum's @E0 MILC command to update a user ONLINE! Because it's too easy to accidentally forget the user-id parameter on the program line - a mistake could cause havoc in your user database. One safeguard against this is to use a .CMD file for all of your single-user updates. The .CMD file might have a name like UPDT.CMD and contain the following statements: IF %1 == . GOTO SYNTAX MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-24 The MBBSEXEC Sysop Maintenance Utility Program Processing a Single User Instead of the Entire Database IF %2 == . GOTO SYNTAX MBBSEXEC %1 %2 GOTO DONE :SYNTAX ECHO USAGE: UPDT MEXFILE USERID :DONE Now, instead of running the MBBSEXEC program directly to update user 321, you'd use the UPDT command file instead: UPDT.CMD LVL50 321 which would be identical to: MBBSEXEC LVL50 321 However, entering: MBBSEXEC LVL50 would cause complete disaster (forgot the userid), whereas: UPDT LVL50 would echo program usage to you instead of running the MBBSEXEC program. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-25 MBBSEXEC 'Simple' Summary You've now learned the language of MBBSEXEC. It is a straight forward, simple programming language with much power. The uses for MBBSEXEC are limited only by your imagination. For example, you could put together a mailing list of all level 10 users, or a mailing list of all people in a certain zipcode. In addition to what you've learned, you can also have multiple "programs" in the same MBBSEXEC program file. For example, to upgrade all users to level 6 from level 5 who've entered 2 or more public messages, and delete all callers who haven't called in the past 90 days, AND delete all messages older than 90 days, AND change the expiration date of all files in area B to "06/01/1990", the following file of MBBSEXEC statements would accomplish the task: ! ! Update Users from level 5 to level 6 ! #CONFIG_FILE: E:\GS\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: USER.LOG #DATABASE: USER #START ! Change Level 5 users to 6 if 2 or more public messages entered if (@level != 5) { goto(skip) } if (@publm >= 2) { @level = 6 @daily_time = 45 @file_u_areas="egi" log("Upgraded from level 5 to 6: /",@ID) log("Lastname: ",@lastname) log("Firstname: ",@firstname) log("# Public Msgs entered: ",@publm) log("-------------------------------") } skip: if(@lastcall == 0) { goto(skip_the_rest) } if(@lastcall < @today - 90) { log("deleting due to lack of calls in 90 days: /",@id) log("Lastname: ",@lastname) log("Firstname: ",@firstname) log("Lastcall: ",@lastcall) @deleted=true MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-26 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC 'Simple' Summary log("---------------------------") } skip_the_rest: #STOP ! !----------------- Now process message database --------------------- ! #CONFIG_FILE: E:\GS\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: MSG.LOG #DATABASE: MSG #START ! skip files with existing expiration dates if (@expdate != 0) { goto(skipexp) } ! ---------- skip if conference area is the "file description" ! ---------- conference area. This area will vary from installation ! ---------- to installation. In our case, 'X' is our conference ! ---------- area for file descriptions. if (@conf == 'X') { goto(skipexp) } if (@date < @today-90 ) { @deleted = TRUE log("Deleted Message: ",@filename) log("Subject: ",@subject) log("--------------------") } skipexp: #STOP ! !----------------- Now process file database --------------------- ! #CONFIG_FILE: E:\GS\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: FILE.LOG #DATABASE: FILE #START MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-27 MBBSEXEC 'Simple' Summary if (@area == 'B') { @expdate = "06/01/1990" log("Changed expiration date of: ",@name) log("Description: ",@brief) log("---------------------------") } #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-28 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC 'Simple' Summary To summarize, MBBSEXEC is a very powerful, yet simple programming language. But you must remember that MBBSEXEC only performs part of the job in some instances. Anytime you have a statement such as: @deleted = TRUE the actual file or message is not really deleted - it's only marked as deleted. To really delete the file, you'll need to log onto your BBS and go into the SYSOP menu. Choose the [S]tatus of Databases command which will perform most of the actual deletions. Next PACK the databases to finish off the deletions. Note that the USER database is not packable. NOTE: YOU MUST BE THE ONLY ONE ONLINE TO PERFORM A PACK OF THE DATABASES! If you assign TRUE to @deleted in the USER database AND you've configured MAGNUM to reuse deleted ID's for new users, the next person that logs on will get that deleted ID. If you assign TRUE to @deleted in the FILE database, files will be deleted whenever someone tries to do a [L]ist of the area the deleted file(s) is in. If you assign TRUE to @deleted in the MSG database, messages are not deleted unless you do a [S]tatus of Databases command from within the sysop menu, and a Pack on the database. If you assign TRUE to @deleted in the RJE database, that record is only marked as deleted, not actually deleted. There is no PACKING facility available for the RJE database due to the nature of the RJEMONIT.EXE daemon process requiring access to the database at any given time! In any event, [S]tatus of Databases and Pack commands from within the Sysop menu will go ahead and perform the actual deletions. IMPORTANT: Running MBBSEXEC.EXE when your BBS is SHUT DOWN (not running) will result in slightly faster execution of MBBSEXEC.EXE. We hope you'll find many good uses for MBBSEXEC, but you must remember to make a backup of your *.DAT and *.KEY files PRIOR to running any MBBSEXEC programs. If you do not have a backup of your databases and run into trouble with the MBBSEXEC program then DON'T bother calling us - there's nothing we can do for you! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-29 MBBSEXEC Advanced Features MBBSEXEC -- ADVANCED SECTION Up until now, we've introduced MBBSEXEC.EXE to you as a simple programming language. If you're not a programmer, what you've learned until now should be just enough to get you started writing .MEX programs which will suit your needs. However, if you are an experienced programmer, preferably in the C programming language, then you'll enjoy this "Advanced Features" section. Non-Programmers may choose to omit the remainder of this chapter, but are welcome to continue. With the Advanced features incorporated into MBBSEXEC, you can have Nested IF() statements, optional ELSE statements for your IF statements, and WHILE() statements. Functions also exist to EXIT() a .MEX program in progress, get INPUT() from users, and perform logging to the console with clog() statements, logging to a binary file with the blog() statement, or logging to a string with the slog() statement. You can run external programs with the SYSTEM() command, create your own .MEX functions and CALL() them, save and restore data which can be used by MSESSION and much more! We'll start out describing the easiest statements and techniques for the sake of those new (or with little exposure) to programming, and progressively work our way into more advanced techniques. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-30 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - the EXIT statement You can exit your .MEX file at anytime with the following statement: EXIT(x) where 'x' is the value to be assigned to the exit code upon exit. Whenever an EXIT(x) statement is executed, MBBSEXEC.EXE will end. The value of the exit code (x) can be tested for if MBBSEXEC was started from a .CMD file (using the ERRORLEVEL variable). A valid EXIT(x) statement might look something like this: EXIT(5) NOTE: Without the EXIT(x) function, MBBSEXEC.EXE always ends with an exit code of 0 or 1. If it ends with 0, it means everything went ok. If it ends with 1, it means it terminated due to some error condition (the cause of the error is displayed upon the abnormal termination). You should keep this in mind when using the EXIT(x) function. For example, you might want to use EXIT(x) where 'x' is a value of 2 or above. The valid range is 0 to 255 and is not checked by the MBBSEXEC program. You can use a @TALLYx variable in place of the 'x' (@TALLYx is explained later). The EXIT(x) function is meant to be used as part of an IF statement. For example, the following illustrates exiting the .MEX file at the 100th record: . . if(@thisrec == 100) { exit(5) } . . Naturally, you'll want to exit() your .MEX program based on some other meaningful information, such as finding the first occurence of a particular last name. @THISREC used above is explained later. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-31 MBBSEXEC Advanced Features - Special Fields in USER database Special Fields in the USER database Certain fieldnames of the USER database area have been designated as being "special". These "special" fields are those which hold up to 26 characters (the letters of the alphabet). The "special" fields are: @FILE_U_AREAS @FILE_D_AREAS @FILE_L_AREAS @MSG_R_AREAS @MSG_W_AREAS @MSG_L_AREAS @CONFERENCES @FREE_DL_AREAS @MILC_CMDS You've learned how to make simple assignments to these fields with statements such as: @FILE_D_AREAS = "ABCFGH" With the new enhancement added to this version, you can ADD areas TO or DELETE areas FROM these special fields. For Example, if the field @FILE_D_AREAS already contains "ABCFGH", and you wish to add areas I and J, you would accomplish it with the following statement: @FILE_D_AREAS = "+IJ" The value of @FILE_D_AREAS would now contain "ABCFGHIJ". If you wish to delete areas B and C from @FILE_D_AREAS (assume it currently contains "ABCFGH"), you would accomplish it with the following statement: @FILE_D_AREAS = "-BC" The value of @FILE_D_AREAS would now contains "AFGH". Summarizing, if you wish to assign to one of these special fields, simply assign as you have in the past. However, if you wish to add to the field, simply make the '+' character the very first character in your assignment string. To remove from the field, simply make the '-' character the very first character in your assignment string. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-32 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - #LOG_FILE: #LOG_FILE: If the parameter to the #LOG_FILE: statement is "STDOUT" (without the quotes) as the name of your log file, then all output will be written to standard output (the console). When written to standard output, the record number display will be supressed, and if you run MBBSEXEC.EXE as a child process of the BBS, then the remote user will be able to view the output. If running MBBSEXEC.EXE as a standalone program (not from the BBS), if the #LOG_FILE: is STDOUT, then output is redirectable (ie: with the OS/2 ">" redirection symbol). If the filename supplied to the #LOG_FILE: statement is appended with a ",A" (without the quotes) after the filename, it will open up the file for Append. For example, the statment: #LOG_FILE: USER.LOG,A will open USER.LOG as the output file and append its output to the end of the file. If the ",A" is omitted, the file specified in the #LOG_FILE: statement will be deleted if it exists prior to its use. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-33 MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters The log() statement is the key to generating Mailing Labels, Form Letters and Reports. To accomplish this, you'll need to become familiar with the enhanced capabilities of the log() statement. Enhanced LOG statement capabilities: The ENHANCED format of the LOG statement is: LOG(PARM1, PARM2, ... PARMn) where: The PARMx arguments can consist of any combination of field variables relating to the current database and/or quoted strings. Examples: log("Name: ",@lastname,", ",@firstname," ",@middlename) log(" ID: /",@id," Last called on ",@lastcall) log("--------------") You can even print mailing labels: log(@firstname," ",@middlename," ",@lastname) log(@street1) log(@street2) log(@city," ",@state,", ",@zip) log(@country) log("") The above assumes 5 printable lines per label, the 6th line being the space separating one label from the next. With the information you've learned so far, you can expand on these capabilities in order to produce form letters. A form letter would typically consist of many log() statements contain quoted strings as the message body, with a few '@' variables thrown in where appropriate. Generally, form letters will be written to users matching specific criteria, skipping those who don't match. For illustrative purposes, a simple form letter generated to all users of a subscription board who are about to expire within the next 30 days might look something like the following: #CONFIG_FILE: D:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: PRN #DATABASE: USER #START if(@memodate1 == 0) { goto(skipit) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-34 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters } if(@today + 30 > @memodate1) { log("") log("") log("") log("") log("") log(" ",@today) log(" ",@firstname," ",@middlename," ",@lastname," (ID: /",@id,")") log(" ",@street1) log(" ",@street2) log(" ",@city," ,",@state," ",@zip) log("") log("") log(" Dear ",@firstname," ",@lastname) log("") log(" Our records show that your BBS subscription is about to") log(" expire on ",@memodate1,".") log("") log(" Don't miss out! Get uninterrupted service by renewing your") log(" BBS Subscription today!") log("") log("") log(" Sincerely,") log("") log("") log("") log("") log("") log(" John Sysop") log("") log(@\12) } @tally1 = @tally1 + 1 skipit: if(@thisrec == @hirec) { log(@tally1," letters generated",@\12) } #STOP In the above example, please note that the @\12 parameter translates to a FormFeed character (tells printer to advance to the top of next page). In order to send characters to your log file or device (ie: printer) which cannot be entered by pressing a keyboard key, you may still send that character to the log by using its decimal equivalent. The decimal equivalent for FormFeed is 12, thus @\12 tells the log() statement to send a FormFeed to the printer. The format is the following: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-35 MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters @\x where 'x' is the decimal equivalent of the character you wish to send to the log. This is an ideal way to send escape sequences to your printer in order to change fonts, print size, etc. For example, an escape sequence of "<Esc><Ctrl-X><Ctrl-Y>Hello" would be entered as follows: log(@\27,@\24,@\25,"Hello") The following ADVANCED KEYWORDS allow you to produce reports: @LOREC - indicates record 0 (the first record in a database) @HIREC - indicates record X (the last record in a database) @THISREC - indicates the current record being processed @TALLY0 - Tally counter number 0 @TALLY1 - Tally counter number 1 . . @TALLY98 - Tally counter number 98 @TALLY99 - Tally counter number 99 The @TALLYx counters can be used to count whatever you wish, or can be used for other purposes such as flags. With the introduction of the modified/enhanced LOG statement, you can actually generate FORM LETTERS, and with the introduction of the new KEYWORDS above, you can generate detailed reports! Initially, upon start of processing, @LOREC is set to 0, @HIREC is set to the highest record number, @THISREC varies with the current record number, and the @TALLYx counters are set to 0. The @HIREC, @LOREC and @THISREC variables are to be used for comparisons only, they must not be used as the target of an assignment statement. The @TALLYx variables are to be used however you wish. NOTE: The @LOREC, @HIREC and @THISREC variables are typically used to generate report headers and summaries at the beginning and ending of processing. Please note that the use of these will cause an increase in your processing time! The following example will print mailing labels for all level 30 users on the system. When finished with the labels, it will generate a small report stating how many mailing labels were generated and what percentage of the users on the system are at level 30. Each label is assumed to consist of 5 printable lines, and 1 blank line separating the labels. The header and summary will each consume 1 label: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: LEVEL30.LOG #DATABASE: USER #START MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-36 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters if(@thisrec == @lorec) { log("The following is a list of Level 30 Users") log("") log("") log("") log("") log("") } if(@level==30) { log(@firstname," ",@middlename," ",@lastname) log(@street1) log(@street2) log(@city,", ",@state," ",@zip) log(@country) log("") @tally5 = @tally5 + 1 } @tally9 = @tally9 + 1 if(@thisrec == @hirec) { log("End of list for Level 30 users") log("There were ",@tally5," users printed") log(@tally9," total records processed") @tally5 = @tally5 * 100 @tally0 = @tally5 / @tally9 log(@tally0,"% of the users are at Level 30") log("") log("") } #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-37 MBBSEXEC Advanced Features - Strings, Binary & Console Output Much like the @TALLYx variables available to you, there are also string variables available to you: @STRING0 @STRING1 . . @STRING99 Each of these variables is capable of holding up to 100 bytes. You can assign any other string variables to/from these @STRINGx variables. You can use these variables however you please. In addition to the enhanced LOG() statement, an SLOG() statement also exists which writes its output to a @STRING variable rather than the log file. The format is: SLOG(x,parm1,...,parmn). It is identical to the LOG() statement except that the first parameter (x) tells the SLOG() statement which @STRINGx variable to write to. For example, the statement: slog(5,@firstname," ",@middlename," ",@lastname) would result in writing the above parameters to @STRING5. When the statement completes, @STRING5 might hold a value such as "John S Doe". The slog() statement was necessary for this type of combination because string variables do not have an append operation such as '+'. Note that a CR/LF (carriage return/linefeed) is NOT appended to the end of the string. log() statements append a CR/LF to the output. slog() and blog() statements do not. If you wish to create your own binary (random access) file as output, you can do so with the BLOG() statement. The BLOG() format is: BLOG(x,parm1,...,parmn). It is identical to the writing the LOG() statement except that the first parameter (x) tells the BLOG() statement how many bytes to write. For example, the statement: blog(50,@firstname," ",@middlename," ",@lastname) would result in writing 50 bytes to the output file (the output file is the filename in the #LOG_FILE statement). If the result is longer than 50 bytes, only the first 50 bytes are written. If the statement being written is shorter than x, the difference is padded with nulls (binary 0's). By using blog() statements instead of log() statements, it is possible to create your own binary (random access) output files this way. Note that CR/LF (carriage return/linefeed) are NOT appended to blog() statements. Only the log() statement appends a CR/LF. When opening an existing binary log file for append mode, do not use a ",A" (without quotes) after the #LOG_FILE file name. Instead, use ",U" (without quotes) to indicate binary update mode. This simply tells MBBSEXEC not to write the "* * * Append * * *" string which it normally does when ",A" is used. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-38 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Strings, Binary & Console Output When using blog() statements, take care not to use log() statements! Note that the @\x variable is available for log(), slog() and blog() statements. If you wish to print a message to the console (regardless of the value of the #LOG_FILE paramater), you can use the clog() statement. It's operation is identical to that of the log() statement except that its output always goes to the console, whereas the log() statement's output always goes to the file specified in the #LOG_FILE statement. For technical users, the output of the clog() statement is printed to the console via stderr (ie: can be redirected with "2>filename"). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-39 MBBSEXEC Advanced Features - the INPUT() statement Your .MEX programs are capable of interacting with the user in order to receive user input. User input can be directed to a @STRINGx or @TALLYx variable. The format of the INPUT() statement is as follows: INPUT("input text",@TALLYx) or INPUT("input text",@STRINGx) When the MBBSEXEC.EXE program executes an input statement, it prints the contents of "input text" on the console and waits for the user to type their input. An example of an input() statements follow: input("What is your name => ",@string1) input("How old are you => ",@tally1) Input() statements might generally be found in .MEX files that search for some criteria without having the need to edit the .MEX file every time the criteria changes. For example, to search for one or more occurrences of a certain last name, the following statements might be used: #START if(@thisrec == @lorec) { input("Lastname to Search For => ",@string1) } ! ! clog("Comparing ",@\34,@lastname,@\34," and ",@\34,@string1,@\34) ! if(@lastname == @string1) { clog("Name: ",@lastname,", ",@firstname," ",@middlename) clog(" ID: /",@id) clog("From: ",@city," ",@state," - ",@country) clog("Last Called on ",@lastcall) clog("- - - - - - - - - - - - - - -") input("Search for Next Occurence (Y/N) => ",@string2) if(@string2 == "N") { exit(0) } } #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-40 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - the WHILE() statement Much like the IF() statement, the WHILE() statement is identical in format: IF(expression) { . . } WHILE(expression) { . . } The only difference between the two is that when an IF() statement ends (matching } found), the program continues with the next statement. With a WHILE() statement, the WHILE() loop repeats continuously until (expression) becomes false. For exmple: @tally5 = 1 while(@tally5 != 0) { input("Enter a number (0 to quit) => ",@tally5) clog("You picked ",@tally5) } clog("Ok - the WHILE() loop is now over!") The reason the WHILE() statement is similar is because if (expression) is TRUE, then the statements following, enclosed in { and } are executed. If (expression) is FALSE, program execution continues with the statement following the } brace which matches the { brace on the WHILE() line. The difference between IF() and WHILE() when (expression) is TRUE is that the WHILE() loop repeats itself until (expression) becomes FALSE. This was easily demonstrated with the example above. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-41 MBBSEXEC Advanced Features - The } ELSE { statement As mentioned earlier, IF() statements can have matching ELSE statements. The format of an ELSE statement is: } ELSE { all on one line. Each ELSE matches up with the matching { of an IF() statement. And because IF() statements can be nested, so can ELSE statements: if(expression) { . . if(expression) { . . } else { . . } } With the introduction of the ELSE statement, we can simplify many things. For example, the following statements: if(@level > 10) { . . goto(done) } . . done: Could be replaced with: if(@level > 10) { . . } else { . . } thus eliminating the need for the GOTO statement and its associated label alltogether. NOTE: The } ELSE { statement can also be replaced with ELSE (no brackets). Should you desire to use ELSE without the brackets, MBBSEXEC.EXE will internally add the brackets for you. Whether you use these brackets or not is entirely up to you. Some people argue MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-42 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - The } ELSE { statement that the use of brackets improves readability while others argue that the brackets decrease readability. Nesting levels ( { and } within other { and } ) can be up to 200 levels deep. Extreme caution must be taken when using the GOTO statement when inside a { and } pair or when branching to another { and } pair. For example, in a nested IF ... ELSE statement, it's ok to issue a GOTO to a label within the same matching { and } pair. It's even ok to issue a GOTO from within a { and } pair to the main execution part of the .mex file (ie: not contained within a { and } pair). However, if you're branching to a label within a { and } pair and the GOTO was issued from outside that { and } pair, the results will be highly unpredictable. Example: IF(expression) { . . if(expression) { . badlabel: . goto(ok1) . . ok1: . } . goto(ok2) . } else { . goto(badlabel) . } ok2: Note the branch to ok1 is valid because the label is contained within the same { and } bracket pair as the goto statement. The branch to ok2 is valid because the ok2 label is in the main program body (not within a { and } pair. However, the branch to bad label goes from one { and } pair to another { and } pair and therefore, the results of this branch will be highly unpredictable. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-43 MBBSEXEC Advanced Features - Indirect Addressing (Indexing) @TALLYx and @STRINGx statements can have the 'x' part of the statement indirectly addressed (indexed) by another @TALLYx variable. For example, the statements: @TALLY5 = 15 @TALLY[5] = @TALLY[5] + 1 the first statement assigns the value 15 to @TALLY5. The second statement indirectly references @TALLY15 by specifying [5] instead of using 15 as part of the name. The [5] specifies to get which tally variable you're looking for from the value stored in @TALLY5. The same logic applies when using [x] with @STRINGx. For example, if @TALLY5 holds the value 15, then @STRING[5] is identical to specifying @STRING15. Since it can become confusing to use @TALLYx statements for your indexes, you may substitute the word @INDEXx in place of @TALLYx. Using the above example, the following become more readable: @INDEX5 = 15 @TALLY[5] = @TALLY[5] + 1 MBBSEXEC internally converts @INDEX to @TALLY - using either method results in an identical result (they both reference the same @TALLYx variable). When using indirect addressing, you can also use pre-increment, post-increment, pre-decrement, or postdecrement. Examples of Pre-Increment: @INDEX5 = 20 log(@TALLY[+5]) is identical to: @TALLY5 = 20 @TALLY5 = @TALLY5 + 1 log(@TALLY21) Examples of Post-Increment: @INDEX5 = 20 log(@TALLY[5+]) is identical to: @TALLY5 = 20 log(@TALLY20) @TALLY5 = @TALLY5 + 1 Pre-Decrement and Post-Decrement work the same way as the increment operation except that it subtracts 1 instead of adds 1, and the '-' sign is used instead of the '+' sign. You can also use a pre-increment or pre-decrement operation AND a MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-44 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Indirect Addressing (Indexing) post-increment or a post-decrement operation in the same statement: @TALLY5 = 20 log(@TALLY[+5+]) is identical to: @TALLY5 = 20 @TALLY5 = @TALLY5 + 1 log(@TALLY21) @TALLY5 = @TALLY5 + 1 IMPORTANT: "EQUATED" names can NOT use indirect addressing (indexing)! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-45 MBBSEXEC Advanced Features - Equating names for @TALLY/@STRING Because it can be very frustrating using @STRINGx and @TALLYx variable names, the EQUATE: keyword has been added. This keyword can redefine the variable names used so that you can use more meaningful names: EQUATE : USER_NAME_FIELD = @STRING10 EQUATE : LEVEL5_COUNTER = @TALLY42 The equated name you plan on using (ie: USER_NAME_FIELD from the above example) must follow certain rules: - The name must not exceed 30 characters in length. - The first character must be alphabetic (A-Z) or the '@' character. - Valid characters in the name consist of: alpha (A-Z), digits (0-9), and the '_' (underscore), '.' (period), and '@' characters. With the ability to 'equate' your own variable name with a @STRINGx or @TALLYx variable, you can have statements such as: user_name_field = @lastname if(@level == 5) { level5_counter = level5_counter + 1 } which would be identical to: @string10 = @lastname if(@level == 5) { @tally42 = @tally42 + 1 } Note that EQUATE statements may appear anyplace in your .MEX file, however, you cannot use the equated name in your file if it appears before the equate statement. The use of equated names are to appear after the equate statement! You can have up to 200 EQUATE statments (100 for @TALLY0 thru @TALLY99, and 100 for @STRING0 thru @STRING99). Equated names can NOT be indirectly addressed (indexed) using the equated name, but can be indirectly addressed using @STRING[x] or @TALLY[x]. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-46 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features -Writing/calling your own functions To declare a function anywhere in your .MEX file, it must start with the FSTART:FUNCNAME and end with the FSTOP:FUNCNAME parameter. Examples: . . FSTART:func1 . . . FSTOP:func1 . . FSTART:func2 . . . FSTOP:func2 . . Function names (ie: func1, func2, etc) can be any name you wish, up to 30 characters in length. During normal program execution, functions (program statements appearing between FSTART:funcname and FSTOP:funcname statements) are not executed unless explicitly called. You may declare up to 100 functions in any .MEX program (ie: up to 100 functions between any set of #START and #STOP statements). To call a function from within currently executing program statements: . . CALL(func1) . . When MBBSEXEC comes across a CALL() function, it passes control to the function being called. When the function finishes, control is returned to the next statement after the CALL() statement. Calls can be nested up to 100 levels deep. Optionally, if you have a function name in a @STRINGx variable, you can use that @STRINGx variable as the parameter to the CALL() function. Example: @STRING5 = "func1" . . CALL(@STRING5) . . MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-47 MBBSEXEC Advanced Features -Writing/calling your own functions This capability can come in handy when using CLOG() and INPUT() statements to form a menu: @string1 = "func1" @string2 = "func2" @string3 = "func3" @string4 = "func4" clog("0 - Exit Program") clog("1 - Do func1") clog("2 - Do func2") clog("3 - Do func3") clog("4 - Do func4") @tally0 = 0 while(@tally0 == 0) { input("Choice (1-4) => ",@tally0) if(@tally0 == 0) { exit(2) } if(@tally0 > 4) { @tally0 = 0 } } call(@string[0]) To terminate a function early (ie: without processing the rest of the function statements), you may issue the RETURN command: fstart:func1 . . if(expression) { return } . . fstop:func1 Alternately, you can set the @RESULTCODE (a read-only variable) with the RETURN statement when using the format: return(x) where 'x' is a numeric value to be placed in the @RESULTCODE variable. 'x' can also be a @TALLYx variable. If you plan on checking the value of the @RESULTCODE variable after calling a function, it must be tested immediately after the function call: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-48 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features -Writing/calling your own functions . . call(func1) if(@resultcode == 0) { . . } else { . . } . . NOTE: The RETURN command is to be used only within a function. IMPORTANT: The GOTO() statement, if used within a function, is to be used ONLY to branch to a label contained within that function!! NOTE: You can improve performance (ie: speed) of the processing of your .MEX files by using function declarations and function calls. For exmaple, the following code: if(expression) { . . . . } will run slower than: if(expression) { call(funca) } where "funca" would contain the same code as is between the braces of the "if(expression)" statement above. This is especially true when large numbers of statements appear between the brackets of the if() statement. To clarify this further, the speed improvement comes about when the if(expression) statement evaluates to "false". Because MBBSEXEC is an interpreter, it must read (and ignore) every line of code after the if() statement until it finds its matching brace. However, with the call() statement, it's only one statement which is read (and ignored) in the case of the if() statement evaluating to "false". MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-49 MBBSEXEC Advanced Features -Setting the NEXT record to Process The function SETREC(x) sets the next record number to get. The function only "sets" the next record but doesn't actually retrieve it until the #STOP statement is encountered, which forces the read of the next record and executes the code at the #START statement again. The 'x' portion can be either a hard-coded number or a @TALLYx variable. Here's an example of how SETREC(x) might be used: #START if(@tally0 == 0) { clog("Record Range: 0 to ",@hirec) goto(skip_firstime) } clog("ID: /",@id," Name: ",@firstname," ",@middlename," ",@lastname) skip_firstime: @tally0 = 1 input("Record number to fetch => ",@tally1) setrec(@tally1) #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-50 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Executing an External Program You can run an external program by using the SYTEM() call: system("pgmname.exe parm1 parm2") The above example calls PGMNAME.EXE, passing it two arguments: PARM1 and PARM2. The argument to the SYSTEM() command can be within a quoted string, or can be a @STRINGx variable: @string1 = "pgmname.exe parm1 parm2" system(@string1) The parameter to the SYSTEM() call MUST include the full program name including the .exe extension. If it is not in the current directory, you should include the complete filespec (drive,path,filename and extension: "C:\MAGNUM\EXT_DIR\PKUNZIP2.EXE"). NOTE: The SYSTEM() command sets the @RESULTCODE (a read-only variable). If you wish to obtain the resultcode, it should be checked immediately following the SYSTEM() call: system("pgmname.exe parm1 parm2") if(@resultcode == 1) { exit(1) } If the program cannot be found or started, the @RESULTCODE variable will be set to -1. Otherwise, it will be set to the value the called program sets at termination. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-51 MBBSEXEC Advanced Features-Save/Restore/Start/Delete Pgm Data Your .MEX program can save its data (@TALLYx and @STRINGx) with the SAVE_DATA(filename) command. This command saves the values of all @TALLYx and @STRINGx variables to the file specified by 'filename'. The 'filename' paramater can be a quoted string or a @STRINGx variable. Valid Examples: SAVE_DATA("e:\mex1data.var") or SAVE_DATA(@STRING5) Once a datafile is saved, it may no longer be needed when your program finishes. For this reason, we've added the command DELETE(filename), which can have the format: DELETE("e:\mex1data.var") or DELETE(@STRING5) Your .MEX program can restore the data (@TALLYx and STRINGx) previously saved with the SAVE_DATA(filename) command by using the command RESTORE_DATA(filename). The 'filename' parameter can be a quoted string or a @STRINGx variable. Valid Examples: RESTORE_DATA("e:\mex1data.var") or RESTORE_DATA(@STRING5) As before, when starting out the MBBSEXEC.EXE program, you can optionally place a userid on the command line after the filename: MBBSEXEC filename[.mex] [userid] Now, the syntax is: MBBSEXEC filename[.mex] [userid] [@datafile] If you plan on using the [userid] parameter, it must be the first paramater after the "filename[.mex]" parameter. The [@datafile] parameter gives the filespec of the datafile to be loaded (values of @TALLYx and @STRINGx variables) at program startup. The @ symbol preceeding the filename is not part of the filename, but merely an indication to the MBBSEXEC.EXE program that a datafile follows. Examples: MBBSEXEC LEVEL20 1 @MEXDATA1.VAR MBBSEXEC REPORT @MEXDATA2.VAR The datafile is an ASCII text file, whose format is: @TALLY0 = 15 @TALLY1 = 3421 . . @TALLYn = 0 . . @STRING0 = "This is string 0" @STRING1 = "String 1" MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-52 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features-Save/Restore/Start/Delete Pgm Data . . @STRINGn = "String n" You need only specify the variables you wish to be initialized with the data you provide. This file is in the same format as the "filename" specified by the SAVE_DATA("filename") and RESTORE_DATA("filename") commands, and can also subsequently be used at runtime by the RESTORE_DATA("filename") command. The SAVE_DATA() command can take a null parameter. For example, the command SAVE_DATA("") will save the data to the file from which the MBBSEXEC.EXE program was started with if the @datafile parameter was used at startup. In other words, if MBBSEXEC was started with: MBBSEXEC @mexvars.tmp then the SAVE_DATA("") command will is equivalent to issuing the command: SAVE_DATA("mexvars.tmp") Likewise, the command RESTORE_DATA("") is equivalent to: RESTORE_DATA("mexvars.tmp") Utilizing the SAVE_DATA(), RESTORE_DATA(), and SYSTEM() commands, it's possible to cross-reference between databases. For example, if you wish to Process the FILE database, but want the name of the person who uploaded the file, the .MEX file processing the FILE database would look something like the following: @tally1 = @who save_data("findout.tmp") system("e:\magnum\pgm_dir\mbbsexec.exe findul @findout.tmp") restore_data("findout.tmp") clog("File ",@name, "was uploaded by ",@string1) and the .MEX file called would process the USER database as follows: if(@thisrec == @lorec) { setrec(@tally1) } else { slog(1,@firstname," ",@middlename," ",@lastname) save_data("") exit(2) } The data saved by the SAVE_DATA() command can be read by MSESSION with the MILC command @&x which causes the saved values of @TALLYx and @STRINGx variables to be read/mapped into MSESSION's @Nx an @Zx variables. The RESTORE_DATA() command can read a data file stored with MSESSION's MILC command @$x which will read/map MSESSION's @Nx and @Zx MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-53 MBBSEXEC Advanced Features-Save/Restore/Start/Delete Pgm Data variables to MBBSEXEC's @TALLYx and @STRINGx variables. This feature of reading/saving/mapping MSESSION and MBBSEXEC data allows the two programs to communicate and provides for an ideal way of passing information to/from MBBSEXEC if MSESSION calls MBBSEXEC as a child process (door). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-54 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features-The EXTRACT() function The EXTRACT() funtion can extract a string from within another string. This function requires four (4) parameters: EXTRACT( target_string, source_string, start_position, byte_count ) This function can extract any portion of source_string and place that extracted portion into target_string. For example: @string1 = "Hello there, my name is Joe" @string2 = "name" if(@string1~@string2) { extract(@string3,@string1,@resultcode,9) } The above code sample uses @string3 as target_string, @string1 as source_string, @resultcode as start_position, and 9 as byte_count. The statement extracts from @string1 (the source_string), 9 characters (the byte_count) beginning at position 17 (the start_position of where "name" appears within @string1. The resultant target_string (@string3) will contain (without the quotes): "name is J" Now for the rules: target_string: must be either a @STRINGxx variable or a number. If a number, the number represents which @STRINGxx variable to use. source_string: must be either a @STRINGxx variable or a string literal (enclosed in doublequotes - ie: "hi there"), or a number. If a number, the number represents which @STRINGxx variable to use. start_position: must be one of: a @TALLYxx variable, the @RESULTCODE variable, or a number. byte_count: must be one of: a @TALLYxx variable, the @RESULTCODE variable, or a number. NOTEs: - no indirect addressing is allowed within any of the EXTRACT() parameters! - if the value of start_position is out of bounds during runtime, the program will abort with an error message which states the contents of the variables. Under normal operations this should never happen. - If the value of byte count is more than the number of bytes in the string from the starting position, then only the number of bytes left in the string will be extracted. For example, if you find the word "music" in a string and want to extract the entire string from that word on, set the byte_count parm to 999 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-55 MBBSEXEC Advanced Features-The EXTRACT() function or some other large number. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-56 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Sample .MEX Programs The following demonstrates a practical use for a .MEX program which searches your USER database based on a lastname which it prompts you for: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: stdout #DATABASE: USER #START if(@thisrec == @lorec) { input("Lastname to Search For => ",@string1) } ! ! log("Comparing ",@\34,@lastname,@\34," and ",@\34,@string1,@\34) ! if(@lastname == @string1) { log("Name: ",@lastname,", ",@firstname," ",@middlename) log(" ID: /",@id) log("From: ",@city," ",@state," - ",@country) log("Last Called on ",@lastcall) log("- - - - - - - - - - - - - - -") input("Search for Next Occurence (Y/N) => ",@string2) if(@string2 == "N") { exit(5) } } #STOP The following demonstrates a sample .MEX programs which utilize most of the techniques covered in the advanced section. The purpose is to provide a sample of how these functions might be put together: ! ! Sample .MEX program to provide numbers of how many users are in ! each security level (you need to change the @level statements to ! match your particular system). ! #CONFIG_FILE: e:\magnum\pgm_dir\mbbsinit.1 #LOG_FILE: FIND.LOG #DATABASE: USER #START ! ! Equate our names with MBBSEXEC names for readability ! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-57 MBBSEXEC Advanced Features - Sample .MEX Programs equate : level5 = @tally1 equate : level6 = @tally2 equate : level10 = @tally3 ! Used for level 10 tally equate : level15 = @tally4 equate : level20 = @tally5 equate : level30 = @tally6 equate : over_level_30 = @tally7 equate : active_users = @tally8 equate : deleted_users = @tally9 equate : total_users = @tally10 ! ! ---------- DETERMINE - function to determine user level ! fstart:determine ! function to determine user level if(@level == 5) { ! check for level 5 level5 = level5 + 1 ! increment if true } else { ! otherwise if(@level == 6) { ! check for level 6 level6 = level6 + 1 } else { if(@level == 10) { level10 = level10 + 1 } else { if(@level == 15) { level15 = level15 + 1 } else { if(@level == 20) { level20 = level20 + 1 } else { if(@level == 30) { level30 = level30 + 1 } else { if(@level > 30) { over_level_30 = over_level_30 + 1 } fstop:determine ! end procedure ! ! ------- FINISHUP - function to report results - called at last record ! fstart:finishup clog(@\13@\10) clog("Level 5 Users: ",level5) ! log level5 users clog("Level 6 Users: ",level6) clog("Level 10 Users: ",level10) clog("Level 15 Users: ",level15) clog("Level 20 Users: ",level20) clog("Level 30 Users: ",level30) clog("Users >Level30: ",over_level_30) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-58 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Sample .MEX Programs clog("- - - - -") clog(" Active Users: ",active_users) clog("Deleted Users: ",deleted_users) clog(" Total Users: ",total_users) log("Level 5 Users: ",level5) log("Level 6 Users: ",level6) log("Level 10 Users: ",level10) log("Level 15 Users: ",level15) log("Level 20 Users: ",level20) log("Level 30 Users: ",level30) log("Users >Level30: ",over_level_30) log("- - - - -") log("Active Users: ",active_users) log("Deleted Users: ",deleted_users) log(" Total Users: ",total_users) fstop:finishup ! ! --------- Main Processing (Main Program Body) -------- ! total_users = total_users + 1 if(@deleted == FALSE) { call(determine) active_users = active_users + 1 } else { deleted_users = deleted_users + 1 } if(@thisrec == @hirec) { call(finishup) exit(5) ! exit the program with return code of 5 } #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-59 MBBSEXEC -- Program Summary (All Sections) If you've completed this chapter from start to finish, then you have a fairly good grasp of the endless capabilities of the MBBSEXEC program and its power. Because MBBSEXEC gets its input from STDIN, and writes its output to STDOUT and/or STDERR, it can also be run as a child process (door) under the BBS. This gives added functionality to the program. The remainder of this chapter summarizes the MBBSEXEC commands. General Rules - The .MEX file must be an ASCII text file, created with a text editor which ends every text line with a CR/LF pair. - No text line may exceed 120 characters. - No .MEX file can exceed 64,000 bytes (filesize). - Maximums: up to 500 Labels up to 200 brace levels up to 100 function declarations up to 100 function call nesting (ie: similar to a stack) - Each { must have a matching } and vice versa. - GOTO restrictions: - If used within a function, the label (target) must be within that function. - If used outside of a function, the label (target) should appear within the same set of braces. - Branching to a label in the main program body (brace level 0) is acceptable anywhere except from within a function. All .MEX programs start with: #CONFIG_FILE: Full filespec to MBBSINIT.x #LOG_FILE: Filespec or devicename to write to (ie: PRN) #DATABASE: One of USER, FILE, MSG, RJE, UTILIZ #START and end with: #STOP The filename given in the #LOG_FILE statement is where all log() or blog() statements are written to. If ",A" (without the quotes) follows the filename, the log file is appended to. If you plan on using only blog() statements and wish to append to the file, use ",U" (without quotes) after the filename instead. If the filename is STDOUT, then output will be routed to the standard output device (console) and this name should NOT be followed by ",A" or ",U". If processing the USER database, a record number can optionally follow the #START statement. This will cause MBBSEXEC to process only that record number, then terminate the program. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-60 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC -- Program Summary (All Sections) All .MEX executable program statements must appear between the #START and #STOP program directives. All .MEX executable program statements NOT appearing between { and } (beginning and ending braces) or between FSTART and FSTOP are considered to be part of the MAIN PROGRAM BODY. If a syntax or other error occurs while processing your .MEX file where MBBSEXEC issues a line number referencing the error, MBBSEXEC creates a numbered file with an extension of .SNP (snapshot) - the line number in which the error occurred will refer to the line number of the .SNP file. For example, if your program is UPDATE.MEX and MBBSEXEC terminates due to an error on line 45, the MBBSEXEC creates a numbered file called UPDATE.SNP - line 45 of UPDATE.SNP is where the error occurred. IF() statements and WHILE() statements are of the format: IF(expression) { . . } and WHILE(expression) { . . } The opening brace ( { ) MUST appear on the same text line as the IF() or WHILE() statement itself. The (expression) part of the IF() or WHILE() statement MUST compare two values, separated by one of 7 available comparators: == test for equality >= test for greater than or equal to <= test for less than or equal to != test for not inequality > test for greater than < test for less than ~ test for string2 within string1 (strings only) The format of an ELSE statement is: } ELSE { or ELSE if using braces, they must appear all on the same line as the actual ELSE statement. Every ELSE statement MUST have a matching IF() statement. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-61 MBBSEXEC -- Program Summary (All Sections) All { and } pairs must match up (there should be the same number of { braces as } braces). Nesting ( { and } within other { and } ) must not exceed 200 levels of depth. The MAIN PROGRAM BODY is considered to be level 0. ALL DATES are stored in US date format (MM/DD/YYYY) and must always be 10 characters in length. All STRING comparisons against dates must be in US date format and must always be 10 characters in length. All date string assignments must be in US date format and must always be 10 characters in length. The exclamation mark (!) denotes a comment. Comments are ignored by MBBSEXEC (stripped out internally). A comment ends when the physical text line holding the '!' character ends. The exclamation mark (!) is NOT treated as a comment when: - It is immediately followed by an equal sign (!=). - It is enclosed within double quotes ("..!.."). - It is immediately preceeded and followed by the single quote character ('!'). You can EQUATE (substitute) your own variable names for any @TALLYx or @STRINGx variable. You must EQUATE the name before you can use it. The format of an EQUATE statement (via examples) are: EQUATE : MY_NAME = @STRING15 EQUATE : TTL_CALLS = @TALLY9 The names you use in your EQUATEs must not exceed 30 characters, and must not contain any characters other than numeric (0-9), alpha (A-Z), and the '_', '.' and '@' characters. The first character of the name must be alpha. You can write your own functions by beginning your function with FSTART:funcname and ending with FSTOP:funcname. Example: FSTART:print_summary . . . FSTOP:print_summary Program statements appearing within FSTART and FSTOP are never executed unless explicitly called with the CALL(funcname) parameter. Functions CALL(funcname) - Calls a function declared with FSTART/FSTOP. If the called function issues a RETURN(x) statement, the value of @RESULTCODE is set and should be checked immediately after the call if you wish to obtain the value: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-62 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC -- Program Summary (All Sections) CALL(print_summary) IF(@resultcode != 0) { . } BLOG() - Logs (writes) a fixed length record to the #LOG_FILE file. FORMAT: BLOG(length,parm1[,...parmn]) where 'length' indicates how many bytes to write. If the total is longer than 'length', it is truncated to 'length'. If shorter than 'length', it is padded with nulls (binary zeros). CLOG() - Logs (displays) to the console (via STDERR). FORMAT: CLOG(parm1[,...parmn]) LOG() - Logs (writes) a variable length record to the #LOG_FILE file. FORMAT: LOG(parm1[,...parmn]) SLOG() - Logs (writes) a variable length record to a @STRINGx variable. FORMAT: LOG(x,parm1[,...parmn]) where 'x' indicates which @STRINGx variable to write to. IF() { - Covered above under 'General Rules'. } ELSE { - Covered above under 'General Rules'. WHILE() { - Covered above under 'General Rules'. GOTO(label) - Branch to 'label'. 'label' may appear anywhere in the file and must not exceed 30 characters. If branching to 'label' from within nested { and } pairs, or branching to 'label' to within a different { and } pair, the results will be unpredictable. General rules are: Branch to level 0 from anywahere is always acceptable unless the GOTO is issued from within a function (within FSTART and FSTOP statements). Branch from level 0 or from within a { and } pair to a different { and } pair has unpredictable results! LABEL: - Identifies the target of a GOTO statement. LABEL must not exceed 30 characters and must be followed by a colon (:). Up to 500 labels are allowed per .MEX file. EXIT(resultcode) - Causes MBBSEXEC.EXE to end, returning control to the calling program (or .CMD file). 'resultcode' is the exit code the program will end with (can be checked against the ERRORLEVEL command if in a .CMD file). resultcode should range from 2 to 255. Although a resultcode of 0 or 1 is acceptible, MBBSEXEC.EXE normally ends with a 0 or 1 anyway and thus, codes of 0 or 1 should be avoided. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-63 MBBSEXEC -- Program Summary (All Sections) INPUT("input text",@STRINGx) - Displays "input text" and prompts the user to enter something. User input is stored in variable @STRINGx. Input is obtained via STDIN, and can thus be redirected if desired. INPUT("input text",@TALLYx) - Displays "input text" and prompts the user to enter something. User input is stored in variable @TALLYx. Input is obtained via STDIN, and can thus be redirected if desired. If an invalid number is entered (ie: non-digits), the result in @TALLYx will be 0 (zero). RETURN(x) - For function use only. Terminates a currently-executing function. Sets the value of @RESULTCODE to value 'x'. 'x' can be numeric digits or a @TALLYx variable. The alternate form of of RETURN(x) is simply RETURN wihout parens which simply terminates the currently-executing function but leaves the @RESULTCODE unaltered. SYSTEM("pgmname.exe parms") - Executes an external program. The parameter can be a quoted string or a @STRINGx variable containing the information. The @RESULTCODE variable is set after the external program finishes and should be checked immediately after the SYSTEM() call if you wish to obtain the result: SYSTEM(@STRING1) IF(@RESULTCODE > 0) { . } The @RESULTCODE will be -1 if the program could not be run (or found). SETREC(x) - Sets the record number of the NEXT record to read (will be read/processed when the #STOP statement is found). 'x' can be a number or a @TALLYx variable. The value of 'x' must fall within 0 and the value of @HIREC. SAVE_DATA("filename") - Saves the values of the 100 @TALLYx and 100 @STRINGx variables to "filename". "filename" can be in quoted strings or in a @STRINGx variable. RESTORE_DATA("filename") - Restores the values of the @TALLYx and @STRINGx variables from "filename". "filename" can be in quoted strings or in a @STRINGx variable. DELETE("filename") - Deletes "filename" from disk. Filename can be in MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 9-64 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC -- Program Summary (All Sections) quoted strings or in a @STRINGx variable. If a complete filespec (drive,path,filname.ext) is not given, the current directory will be assumed. SNAP("filename") - Writes a snapshot of your .MEX program statements to "filename". EXTRACT( target_string, source_string, start_position, byte_count ) - EXTRACTs a substring from source_string into target_string starting at start_position for a total of byte_count. READ-ONLY VARIABLES: @TODAY - Holds current date. @THISREC - Holds current record number. @LOREC - Holds lowest record number - Always 0. @HIREC - Holds highest record number. @RESULTCODE - Holds result of LAST call to RETURN(x) or SYSTEM(filename) or string compare ( ~ ) functions. USER (PROGRAMMER) VARIABLES: @TALLYx - Holds numeric data. There are 100 tally variables available named @TALLY0 to @TALLY99. @STRINGx - Holds string data. There are 100 string variables available named @STRING0 to @STRING99. @TALLY[x] - Indirectly addresses a tally variable. The tally variable being indirectly addressed is based on the value of @TALLYx. @STRING[x] -Indirectly addresses a string variable. The string variable being indirectly addressed is based on the value of @TALLYx. For both @STRING[x] and @TALLY[x] indirect addressing, the [x] portion can use pre-increment or post-increment ([+x] or [x+]). It can also use pre-decrement or post-decrement ([-x] or [x-]). Optionally, a combination of pre/post-increment/decrement can be used ([+x+] or [-x-] or [+x-] or [-x+]). Refer to section on "Indirect Addressing" for more information. You may use the word @INDEX in place of @TALLY (they are interchangeable and refer to the same thing). @INDEX is internally converted to @TALLY by MBBSEXEC. SPECIAL FIELDS IN USER DATABASE The following fields of the USER database are "special": @FILE_U_AREAS @FILE_D_AREAS @FILE_L_AREAS @MSG_R_AREAS @MSG_W_AREAS @MSG_L_AREAS @CONFERENCES @FREE_DL_AREAS @MILC_CMDS MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-65 MBBSEXEC -- Program Summary (All Sections) These fields hold up to 26 areas (A-Z) each. Rather than assigning to these fields (overwriting what's already there), you can optionally append or delete areas from these fields. Example: @FILE_D_AREAS = "+IM" adds I and M as areas to @FILE_D_AREAS @MSG_R_AREAS = "-SK" deletes S and K as areas to @MSG_R_AREAS --- STARTING MBBSEXEC: MBBSEXEC filename[.mex] [userid] [@datafile] If you plan on using the [userid] parameter, it must be the first paramater after the "filename[.mex]" parameter and must consist of only digits. The [@datafile] parameter gives the filespec of the datafile to be loaded (values of @TALLYx and @STRINGx variables) at program startup. The @ symbol preceeding the filename is not part of the filename, but merely an indication to the MBBSEXEC.EXE program that a datafile follows. Examples: MBBSEXEC filename MBBSEXEC filename 320 MBBSEXEC filename @mexdata.var MBBSEXEC filename 320 @mexdata.var MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank Magnum Utility Programs Page 10-1 LAN (Network Utils): STOPMBBS.EXE, STOPRJE.EXE, KILLPROC.EXE (pgm_dir) The Magnum utility programs STOPMBBS.EXE and STOPRJE.EXE are mainly for those users of Magnum on LAN systems. However, you may benefit from the use of these programs even if you're running a single-node BBS on a single computer. STOPMBBS.EXE CAUTION: This program will cause instant termination of ALL sessions, on ALL machines attached to your LAN and without warning to online users! The intent of this program is to keep users offline while a new version of the software is being installed or vast changes are being made by the Sysop. For Instructions on program use, execute STOPMBBS.EXE without parms. It is advisable that ONLY the system administrator (for LAN users of Magnum) have a copy of this program. STOPRJE.EXE Because the RJEMONIT.EXE program is a daemon process, there's no way to stop it (once its started) short of a system reboot. The STOPRJE.EXE utility program, however, will terminate actively running RJEMONIT.EXE programs on ALL machines. For Instructions on program use, execute STOPRJE.EXE without parms. It is advisable that ONLY the system administrator (for LAN users of Magnum) have a copy of this program. KILLPROC.EXE Magnum calls this program internally, but you can benefit from this program for killing other programs on your system if you know their PID (Process Identification Numbers). For Instructions on program use, execute KILLPROC.EXE without parms. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 10-2 Magnum Utility Programs MAGFUTIL.EXE (A Very Powerful File Maintenance Utility) (pgm_dir) Magnum version 8.xx introduced the automatic long description from compressed files containing the member 'file_id.diz'. This capability is invoked only if the file was 'uploaded', but not if the file was added via the sysop utilities of the sysop menu, and not if it was added via MAGFILE.EXE (which also adds files from MAGDRIVE.EXE). MAGFUTIL.EXE will go through all of your files in all of your file databases and check for 'file_id.diz' within ZIP'd files, and, if it finds it, will use that for the long description. The Syntax of the program can be read by running the program with no command-line parms (ie: MAGFUTIL.EXE). Run it for each MBBSINIT.n file which has a unique SESSION DIRectory (most BBS's have identical SESSION DIRectories for all of their MBBSINIT.n files). In addition to creating long file descriptions, there are a number of other functions available in this program; if you execute MAGFUTIL.EXE without any command-line parms, the following screen of info and instructions will appear: Syntax: MAGFUTIL [d:][path]mbbsinit.n -options Where options are: -z create long descriptions from zipped files containing file_id.diz -d delete expired files -c check for files on disk, if they don't exist, delete records -s size check: update records if files on disk are of different size -t date/time check-updt records w/ actual date/time of files on disk -a sort, ascending chronological order (recommended with -t option) -r report only (no actions/updates) to MAGFUTIL.RPT (in pgm_dir) NOTEs: No spaces within options! z option will take a LONG time to execute. ALL files in all FileBases will be processed. r option reports (only) on selected options. Log of actions/updates written to MAGFUTIL.LOG (in pgm_dir) Examples: magfutil mbbsinit.1 -dc magfutil d:\magnum\pgm_dir\\mbbsinit.1 -z magfutil mbbsinit.1 -dcz *** NOTE: It is HIGHLY recommended that you use the -r option FIRST (with any selected options you may choose) PRIOR to actually performing the functions. The -r option will generate a report to MAGFUTIL.RPT (in your pgm_dir) which will show you what actions would have been taken had you not specified the -r option. This is important information to know and can save you from having MAGFUTIL delete your files due to any miscalculations on your part. Without the -r option, the only other security measure available to you is to back up your ENTIRE system (including all downloadable files)! While -r is no substitute for a backup, it can help you spot potential disasters! The -r function deactivates the functionality of any other selecteed options (except for the sort option), but reports on what these options would have done instead of performing them. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Magnum Utility Programs Page 10-3 MAGFUTIL.EXE (A Very Powerful File Maintenance Utility) WARNING: This program DOES NOT observe remapping (ie: the presence of REMAPDIR.x file(s). Refer to remapping directories in chapt 13. IMPORTANT: - The -a option (sort) will handle a maximum of 32,000 records per database file. - MAGFUTIL does NOT observe remapping!! Run this program only on the server machine (the machine the BBS is running on) if applicable. If the server is using remapping, do not run this program! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank Supplied External and RJE Programs with Magnum BBS Page 11-1 Supplied External (child or 'door') programs Included with your Magnum BBS package is UTILIZ.EXE -an external program providing useful utilization charts of your system. The program can be invoked from the "[D]oor" (child) selection from the main menu. Usage of the program is self-explanatory. This program uses information in the UTILIZ.DAT database in your SESSION directory. This database exists if the TRACK_UTILIZATION parm in your STARTUP.x file(s) is set to Y. Supplied RJE programs 1) MSGLIST.EXE - This program (in conjunction with the ADDRJE.EXE program) creates a compressed file which the user can download, containing all messages on the system of the user's choice (date range & msg areas). This program will generate messages in the popular QWK message format. 2) RJEQWK.EXE - Processes incoming QWK messages created by a user offline, or downloaded from another, unrelated BBS. Again, all can be invoked from the RJE menu's "[L]ist/Execute" command. You might find it beneficial to review the files CHILDREN.BBS (called when [D]oor is invoked from main menu), and RJELIST.BBS (called when [L]ist/Execute is invoked from the RJE menu). These files provide examples of how we've used MILC commands to produce the resultant interaction between user, BBS and external programs. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank The NotePad Facility Page 12-1 Magnum incorporates a NotePad facility. Although not obvious from the menus, you may want to inform your users about it via one of the HELLOx.BBS files or via a message in an external menu. The NotePad serves a variety of purposes for you and your users: The NotePad as a "NotePad" To use the NotePad as merely a "NotePad" (ie: to make notes to yourself), simply press <Ctrl-O> (press O while holding down the Ctrl key). You'll be prompted as to which note # you wish to create or modify (0-99). Up to 100 NotePads are allowed for each user of your BBS. If any NotePads already exist for the user, they'll be displayed (numbered) along with their titles so that the user can pick which NotePad to read or modify. If this is the user's first time depressing <Ctrl-O>, s/he can create a note simply by picking a NotePad number (0-99). In any case, Magnum will take the user into the ANSI message editor and the user can read and/or modify the NotePad. The same ANSI editor is used for creating NotePads as is used for creating messages. The NotePad as a "Cut & Paste" Tool for Messages When responding to or reading a message, you can save the contents of that message into a NotePad by [R]eplying to that Message with the ANSI editor. Once inside the ANSI editor, choose <ESC><ESC> (hit the ESC key twice in succession). An options menu will appear. To save the message (or any portion of) the message you're replying to, choose 'ReRead Original Message w/ Marking Facilities'. Mark the lines of the original message that you're interested in and bring those lines into YOUR response. Choose <ESC><ESC> again and choose 'NotePad Facilities' from the options menu and 'save' your reply (which now contains portions of the original message) into your personal NotePad. When creating a message, you can also bring in text lines from any of your NotePads into your message. Choose <ESC><ESC> and then 'NotePad Facilities'. Follow the appropriate prompts to proceed. The NotePad as a List of User ID's for CC's (Carbon Copies) When entering a NEW message, you can provide ID numbers of users to issue CC's (Carbon Copies) of your message to when you save your message. If you'll be routinely sending CC's to a specific group of users, you can have one (or more) of your NotePads contain a list of those User ID's. When prompted for the ID number of a user to be the recipient of a CC, simply provide the NotePad number instead. Magnum will then use that NotePad to read and process the ID numbers of the users to send CC's to. To have a NotePad contain User ID's, simply create a NotePad (any NotePad number will do), and provide the ID numbers as follows (via example): /10 /55 /203 /44 /8 Note that the CC list is free-form, meaning that you're not limited to MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 12-2 The NotePad Facility one user id per text line. The CC list can be used when, after entering a new message, the CC prompt will ask for who to send the CC to as usual. Instead of replying with /id as in the past (which is still supported), you can repond with #5 (note the #) to signify to use the CC list contained in note #5. After CC's have been processed from note #5, the prompt will re-appear so that you might enter additional CC's (or note #'s with CC lists). If you're using the remote mail facility, the NotePad can also hold CC lists containing remote addresses! Unlike normal recipients (as many of the /ID entries per text line as you wish), a remote user entry is one per line. An example CC list ala a notepad might look like: /10 /55 /32 $1989070000/0 $1989110006/195 /34 /404 The above would generate CC's to ID 10, 55, 32, 34 and 404 on your BBS. It would also generate CC's to the Sysop (/0) of the Magnum system having a serial# of 1989070000 and to ID /195 of the Magnum system having a serial# of 1989110006. CC's sent via notepad#, can have Internet E-mail CC's now. The format is: /nnn(someone@someplace.com) where /nnn is the 'outside mail id' and the actual addressee name is enclosed within parenthesis. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Setting up Additional Copies of Magnum on your LAN Page 13-1 If this is a 2nd (or 3rd, etc) copy of Magnum BBS that you've purchased to allow for additional incoming dialup or 'pipe' lines (requires optional 'pipe' module), you'll need to install this additional copy on a workstation (or server) other than the one your original Magnum BBS is running on. This chapter describes how to set up your additional, serialized copy or copies of Magnum BBS on other workstations and be able to share the databases and files with your original Magnum BBS. If you purchased this additional copy of Magnum and do NOT wish to share the databases and files with your original Magnum BBS, then disregard this chapter. For starters, you'll need to make sure that you supply the serial number of your ORIGINAL Magnum BBS (from your 1st system) in ALL of your STARTUP.x file(s) for this additional copy by specifying that serial number in the PARENT_SERNUM parameter of your STARTUP.x file(s). If you do not supply the same serial number as that of your ORIGINAL Magnum BBS diskette (not that of your new copy of Magnum), then you will not be able to share the databases and damage may occur to your original databases. In addition to setting up the same serial number as that of your ORIGINAL (first) Magnum BBS system, you'll need to set up the workstation that you'll be installing the additional copy of Magnum on to be able to share (have READ/WRITE access) to ALL subdirectories specified in your STARTUP.x file(s) for your original Magnum System. For each STARTUP.* file which exists, bring the file into your favorite text editor and modify the following such that it points to the subdirectories matching that of the server: PROGRAM_DIR: *** (Cannot be shared! Must be unique to add'l copy) SESSION_DIR: BULLETIN_DIR: MENU_DIR: HELP_DIR: DISPLAY_DIR: EXTERNAL_DIR: RJE_DIR: MSG_DIR: WORK_DIR: *** (Cannot be shared! Must be unique for EVERY node) USERS_DIR: SYSOUT_DIR: *** (Cannot be shared! Must be unique to addl' copy) ; ; ------ File Directories ; FILEDIR_A: FILEDIR_B: FILEDIR_C: FILEDIR_D: FILEDIR_E: FILEDIR_F: FILEDIR_G: FILEDIR_H: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 13-2 Setting up Additional Copies of Magnum on your LAN FILEDIR_I: FILEDIR_J: FILEDIR_K: FILEDIR_L: FILEDIR_M: FILEDIR_N: FILEDIR_O: FILEDIR_P: FILEDIR_Q: FILEDIR_R: FILEDIR_S: FILEDIR_T: FILEDIR_U: FILEDIR_V: FILEDIR_W: FILEDIR_X: FILEDIR_Y: FILEDIR_Z: For example, if the Server (original Magnum installation) designates its SESSION_DIR as: E:\MAGNUM\SES_DIR then your workstation's path (additional copy of Magnum) might look something like: S:\MAGNUM\SES_DIR or whatever letter on your server is designated to match the same drive letter that the server uses to house the session directory. The PROGRAM_DIR, WORK_DIR, and SYSOUT_DIR must NOT use the same directories as designated by the server or any other workstation. EACH WORKSTATION MUST HAVE ITS OWN, UNIQUE PROGRAM_DIR, WORK_DIR and SYSOUT_DIR directory names! You may have to manually create these subdirectories on your workstation as well as supply those same names as pathnames for their respective keywords in your STARTUP.* files. The PROGRAM_DIR is the directory where you've installed (or plan to install your additional copy of Magnum). Note that ALL BBS functions are supported (as in your original Magnum) with the exception of Group Chat. Chat is currently limited to those logged onto the same machine (being defined as the machine in which the MBBS.EXE program is running on). In other words, if you have the 9-node version (for example) on your Server, and the 9-node version on your workstation, only the 9-nodes of each machine can be used for Chat within the same group of 9-nodes. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Setting up Additional Copies of Magnum on your LAN Page 13-3 Remapping Directories for your Workstation Remapping of directories is recommended. Unless you're running on a LAN, remapping of directories will be of little to no use to you. To perform remapping of directories, create a file (node specific) in the PROGRAM DIRectory of your workstation called REMAPDIR.x (where 'x' is the node#). The format of this ASCII text file is: oldpath = newpath Wherever 'oldpath' is found, it will be replaced with 'newpath'. Example: D:\MAGNUM\ATM = M:\FONT\ATM D:\MAGNUM\ANNOUNCE = X:\BBS\NOTICES Using the above, a filename of d:\magnum\announce\meeting.txt would become x:\bbs\notices\meeting.txt - the actual filename.ext doesn't change, only the directory path housing that filename.ext changes. Server / netnames are also allowed. For example, the following statement is also valid: D:\MAGNUM\ATM = \\SERVER1\DRIVEX\FONTS\ATM Note that both 'oldpath' and 'newpath' are limited to a maximum of 65 characters each. You may have as many text lines as you wish in this file. NOTE: The intention of remapping is NOT to provide a 'quick & dirty' override to the directory path names you defined in your STARTUP.x file(s), but to override any hard-coded directory names in your displayable files! For example, files which "include" other files (with MILC @Ix command) would only work properly on the server machine (on a network). Although the remapping function DOES provide a 'quick & dirty' override to the directory path names defined in your STARTUP.x file(s), we advise extreme caution when doing so. You should NEVER remap the SESSION or PROGRAM directories! In addtion to MSESSION.EXE, the following programs also observe remapping: MBBSEXEC, MSGLIST. REMAPDIR.x must be in the PROGRAM DIRectory of each workstation, and must remap to the proper places in order for the 'extended msgbase' and 'extended filebase' optional modules to work properly. Also, remapping is required for the 'compressed message list' function of the RJE menu to work. Note that MBBS.EXE and all other .EXE's not listed in the above paragraph do NOT observe remapping. Once again, if you're not running a LAN, re-mapping will be of little to no use to you. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank For Systems using 'Extended File' and/or 'Extended MsgBase' Page 14-1 The 'user' fields FILEBASE and MSGBASE indicate the LAST FileBase and MsgBase the user was in. The next time the user logs on, Magnum will automatically change to these bases. The fields FILEGRP and MSGGRP in every user's records add even more flexibility to the extended MsgBase and extended FileBase modules. Until now, access to certain File and Msg Bases were determined solely by security level. With the FILEGRP and MSGGRP fields, each user can be assigned to a File Group or Msg Group (think of these groups as profiles). By way of example, let's suppose that you set up John Doe (ID: /10) such that his FILEGRP is 3 (you can do this by pulling up record 10 of the User database area of the Sysop menu when logged on as Sysop and changing his FILEGRP to 3; or you can write a .MEX program to perform bulk updates). Regardless, assuming that John Doe (ID: /10) is assigned to FileGrp 3. This means that Magnum will look in your SESSION DIRectory for a file by the name of FILE3.GRP and if it finds it, the contents of this ASCII text file will override the security levels imposed by the FILEBASE.EXE program when you set up your FileBases. If Magnum doesn't find FILE3.GRP, Magnum will act as it did prior to this version: it determines access to the different FileBases by means of security levels set by the FILEBASE.EXE program. Assuming that the file FILE3.GRP exists, the contents might look like the following: ; ; Definitions file for File Group 3 ; ; Users assigned to File Group 3 have access to these File Bases ; regardless of Security Level. ; 1 RWL ; Los Angeles OS/2 User Group.. Override Read/Write/List Access 2 RL ; OS/2 2.0.......................... Override Read/List Access 38 L ; California Real Estate............ Override List Access 224 ; New York Real Estate............... No Override As you may have guessed from the above sample file, the semicolon (;) denotes the beginning of a comment. A comment starts with a semicolon and lasts until the end of that text line. Blank lines are ignored. The above sample allows all users who's FILEGRP field is set to 3 to have access to FileBases 1, 2, 38 and 224. The comments (ie: New York Real Estate) are merely comments and may or may not have anything to do with the content of the actual FileBase denoted by that number. If R appears, READ (or download) access will be given to this FileBase regardless of the READ security level set with the FILEBASE.EXE program. If W appears, WRITE (or upload) access will be given to this FileBase regardless of the WRITE security level set with the FILEBASE.EXE program. If L appears, LIST access will be given to this FileBase regardless of the LIST security level set with the FILEBASE.EXE program. Likewise, the MSGGRP field works in an identical fashion except that it expects to find its information in MSG3.GRP if 3 were assigned to the MSGGRP field of a particular user. NOTE1: The FILEGRP and MSGGRP fields override the ability to ACCESS MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 14-2 For Systems using 'Extended File' and/or 'Extended MsgBase' FileBases and MsgBases which the user would not ordinarily have access to. Furthermore, the .GRP file containing the definitions of a group, can override READ(download), WRITE(upload) and LIST security levels. Note that if a dependency on MEMODATE1 or MEMODATE2 exists within a particular FileBase (as set by FILEBASE.EXE), these parameters will override it! NOTE2: Although you don't need to use groups at all, the use of such groups will definitely demonstrate a speed increase in the presentation of the different FileBases and MsgBases for the user to choose from. NOTE3: For those Sysops running the type of board where each user represents a different company for example, they might want to set up their BBS such that these users only have access to one particular FileBase and one particular MsgBase. Let's suppose that users of XYZ Corp are assigned FileBase 5 and MsgBase 8. The Sysop could then assign 5 to their FILEBASE and 8 to their MSGBASE. Furthermore, the Sysop could disable the "[F]ileBase Change" and "[M]sgBase Change" menu selections by raising the security level of these menu choices to one higher than these users. This, in effect, insures that users of XYZ Corp will only see (and know about) FileBase 5 and MsgBase 8. NOTE4: In that only 255 file groups and 255 message groups are allowed with the extended filebase and extended msgbase, we've added the following feature: - If the file Uxxxxx.MG exists (where xxxxx is the user's id number), this file will be used INSTEAD of any MSG group that user is assigned to. - If the file Uxxxxx.FG exists (where xxxxx is the user's id number), this file will be used INSTEAD of any FILE group that user is assigned to. The format of the Uxxxxx.MG and Uxxxxx.FG files are identical to that of the corresponding .GRP files. If you create Uxxxxx.FG or Uxxxxx.MG files, they are to be placed in the SESSION DIRectory. Do not use leading zeros for the xxxxx portion! Examples: U0.MG - Group File for ID 0 for MsgBase access U156.FG - Group File for ID 156 for FileBase access - When viewing a user's record in the Sysop menu, whatever File Group or Msg Group they're assigned to will be followed by the '*' character if the override file (Uxxxxx.?G) exists for that user. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-1 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) ------------------------------------------- AMMO (Automated Magnum Mailer Option) is built into Magnum systems and allows the Sysop the option of implementing this capability. The term AMMO refers to the link level layer of Magnum systems, while the term RMAIL refers to the user level layer. When we speak of AMMO in this chapter, it will be about setting up and using this option from the Sysop's point of view. When we speak of RMAIL in this document, it will be about using the 'remote mail' facility of Magnum from your caller's point of view. Introduction: ------------- As Sysops, we're all familiar with the callers (users) of your BBS dialing in with their modems (or pipe modules), going to the message section, and reading their mail, responding to their mail, and entering new mail. It's very similar to inter-office mail at a company. With the introduction of RMAIL (remote mail), the callers (users) of your BBS can now do the same thing but are no longer limited to the users of your BBS. They can exchange messages with remote users of remote Magnum BBS systems! The same features that exist currently (receipts, CC's, message forwarding, private mail, public mail, messages to ALL) also exist with RMAIL. Just like mailing a letter via the postal service, the user needs to know the address of someone on a remote system. The address is composed of 2 things: the remote system's serial number, and the remote user's ID number on that system. An RMAIL address looks like the following: $1989070000/0 The $ character specifices that this is RMAIL (not local mail). The 1989070000 number happens to be the serial number of the Gilmore Systems BBS located in Van Nuys, California. The /0 is the user id of the Sysop at that system. In this case, the Sysop is Chuck Gilmore. So the above address is actually the address of Chuck Gilmore at his Van Nuys BBS. Envision that each Magnum System is like a city itself. When you send a letter to someone through postal services (mail), you include the person's name and address on the envelope, along with your name and return address. In the above example, the Magnum Serial# is the equivalent of the "city, state, zip and country" on the envelope, and the ID of the user on that system you're sending mail to is the person's "name". Together, the serial# and name form a complete address. Suppose you want to send a letter to "John Smith" in Chicago. Knowing that John smith is ID /348 on the Chicago BBS, his complete address would be $1991000002/348 ($ specifies RMAIL followed by the 10-digit serial#, the / character and ID). The advantages of using RMAIL as opposed to postal mail is multi-fold: - You don't need to know city, state, zip, country, etc. The serial# MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 15-2 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) is the equivalent of all this information. In most cases, when prompted for serial#, entering the ? character will provide you with a list of serial#'s and a written description. - You don't need to include your 'return address' (Magnum does this for you). - You can compose the message once, then send CC's (carbon copies) to other addresses without having to re-enter the message. - You can request a 'return receipt' to notify you that the message you sent was received by the addressee. - You can rest assured that the message will not get 'lost' or go to a 'dead box' due to illegible writing, or that the postal workers will go on strike! - You can even send 'Junk Mail' (goes to every Magnum system on the mail network associated with AMMO). - You can send 'private mail'. - "Attached" files are also sent to the remote site along with the message... you don't need to send a package with a diskette or have the remote site call your BBS to download a certain file! - etc, etc. By way of example, let's suppose that you are XYZ Corporation with an office in Los Angeles (USA). XYZ Corporation also has branch offices in Chicago (USA), New York (USA), Tokyo (Japan), London (UK) and Bonn (Germany). Each location is running a Magnum System as follows: Location Magnum Serial# ------------- -------------- Los Angeles 1991000001 Chicago 1991000002 New York 1991000003 London 1991000004 Bonn 1991000005 Tokyo 1991000006 To complicate things further, each location is in a different time zone, thus making voice communications difficult in terms of time coordination. Each location needs to communicate vital information with all other offices. In terms of distance, The Los Angeles office is closest to the Chicago office, which in turn is closest to the New York office, which in turn is closest to the London office which in turn is closest to the Bonn office which in turn is closest to the Tokyo office (the exact order we've listed them in the above chart). Now, suppose that someone in the New York office needs to get a message to the London office. They would call the NY BBS with their modem or via 'Pipe Module' on their LAN and enter a message to someone specific at the London BBS. At a predetermined time, the Magnum system in NY "calls" the Magnum system in London and transfers that message (along with any other messages targeted at the London office from New York); during that same transfer, any mail from the London office targeted to the NY office are also transfered. This is known as 'direct' (or point-to-point) RMAIL. Now, suppose AMMO links are set up such that the Los Angeles and Chicago MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-3 offices set up their Magnum systems to exchange mail once (or twice, or as many times as you wish) every day (or twice a week, or as many times as you wish). Likewise, the Chicago and New York offices are set up to exchange mail at some predermined time schedule. The same with the New York<-->London office, the London<-->Bonn office, and the Bonn<-->Tokyo office. XYZ Corporation now has RMAIL capabilities from any of their 6 offices to any other of their 6 offices. In that each office has an AMMO link between their neigboring or closest office, phone costs are minimized. Someone in the Bonn office could send someone at the Chicago office a public (or private) RMAIL message by specifying the Chicago serial# and the ID of the person at that system. In that the Bonn office is linked with the London office, the message first goes to the London office, then to the New York office, and finally to its destination in Chicago. If it is a private message, the users at the London and New York offices will never know about the message. This is known as 'indirect' (or 'store-and-forward') RMAIL. If the volume and frequency of mail between the Bonn and Chicago offices are higher than the other four, a direct link between the Bonn and Chicago office can be set up as well as the existing links. Each Magnum system can have as many links as is desired, and can be set up to exchange mail as many times as desired with whatever systems it desires! We've defined 'direct' (point-to-point), and 'indirect' (store-and-forward) AMMO capabilities so far. In our examples, we spoke of exchanging mail to a specific person (ID) at a specific city (serial#). We also have BROADCAST capabilities. A BROADCAST is where you don't enter a message to a specific user or even to a specific serial#. You enter a message to ALL, and use the word BROADCAST as the RMAIL serial#. This means that every Magnum system on the link will receive the BROADCAST message and address it to ALL. BROADCAST capability is a quick way to post a general message to ALL users on ALL serial#'s on the AMMO link. This has advantages and disadvantages. The advantage to this should be quite obvious; the disadvantage of having MANY systems on the 'link' is that a BROADCAST message could be abused and perceived by many of the users on other systems as 'junk mail'... much the same way as your receiving 'junk mail' at your residence in your mailbox. There are only two possible addressee's of a BROADCAST message: ALL or SYSOPs. If SYSOPs, the message is broadcasted only to the SYSOPs on the AMMO link. In addition to DIRECT, INDIRECT, and BROADCAST mail, ECHO mail also exists. ECHO is similar to 'store-and-forward', however ECHO modifies this to 'store-post-and-forward'. In other words, if someone at the Chicago office chooses to send a message to someone at the Bonn office, the links that it goes through (New York, London) will also post this message on their systems so that the users of their systems can also read and respond to this message. We've covered four types of RMAIL: DIRECT, INDIRECT, BROADCAST, and ECHO. In addition to the four types, all of the usual Magnum mail features can also be used: CC's (Carbon copies), receipts, message forwarding, etc. After you create a message, you can send CC's to both users on the system you've entered the message on, and to remote users MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 15-4 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) on remote systems. You can forward a message to a user on a remote system. You can also request a receipt to be generated and sent to you when the addressee of a message you sent (either local or remote) receives your message. As in the past, the Notepad can be used to contain a list of CC's to send a message to (see the chapter entitled "The NotePad Facility"). With the introduction of RMAIL, the CC's can also contain addresses. See the chapter entitle "The NotePad Facility" for an example of how your users can use the notepad to contain CC lists to both local and remote users. So far, our example situations have been with a small, 6-office Magnum network with only one or two links at each system. Even this small system could have any of its systems linked with any other of its systems. The Tokyo office might open two or three more branches of XYZ Corp in neighboring cities. If it has Magnum systems set up in each of those cities, links from the Tokyo office could also be set up to the other three. It can even exclude those links from its Bonn link (a closed local network) as opposed to making it part of the wide network. There is no limit as to how many systems (serial#'s) can be linked together, and no limit as to how many links each system can have. However, there is a limit of 500 'store-and-forward' serial#'s which can be supported by each direct link, and a limit of 5,000 messages per transmission. We feel that approaching this limit on 'large' systems would be unlikely. ------------------------------------------------------------------------ AMMO - Account Setup: --------------------- Like your USER accounts (each user has an ID number and occupies a record in your USER database), your MAIL accounts also have an ID number and occupy a record in your USER database. A mail account is an AMMO 'LINK' between your system and the system you're setting a LINK with. To set up a mail account (LINK) with another AMMO system, you'll need to coordinate the effort with the Sysop at the system you'll be linking with. Using the "Gilmore Systems BBS" in Southern California (serial# 1989070000) as an example, and YOUR BBS (assume your serial# is 1990000000), follow these directions: 0) NOTE: This is just an EXAMPLE; we're not planning on setting up a link between our BBS and yours. 1) Log onto your own BBS locally (* LOGON at the MBBS "Command => " prompt). Log on as a NEW user with a name something like: Firstname=GILMORE, Middlename=SYSTEMS, Lastname=BBS Choose a password and write it down. Complete the logon procedure, write down the ID number assigned to MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-5 this account, and log off. 2) Call our BBS and leave a message that you'd like to establish an AMMO link with us. Give us: A) Your BBS name. B) The ID number and PASSWORD from step 1. C) Your modem telephone number. D) Preferred days/times you'd like for your system to call ours (this is optional). 3) Call our BBS back in a day or so and we'll have a message for you stating A,B,C and D of step 2 above for the account we've set up for your system. 4) Log onto your own BBS locally (* LOGON at the MBBS "Command => " prompt). Log on as SYSOP this time. If you don't have your COLOR settings ON, we suggest you turn them on for this logon. A) Go into the SYSOP Menu, USER database area. B) Pull up the record of the ID number you gave us the day before. C) Change TYPE to M (enter the word TYPE and press ENTER; you'll be prompted for new TYPE; respond with M for MAIL). After you've changed the TYPE to M, the remaining fields to fill in will appear in RED. D) Change SYSTEM_SERIAL# (enter the word SYSTEM_SERIAL# and press ENTER; you'll be prompted for new Serial#;ID;password) Enter the Serial# of the system you'll be setting up a link with (in this case, our system), followed by a semicolon, the ID number we gave you, another semicolon, and the password we gave you. E) Note that PHONE1 and PHONE2 have been changed to DIALCMD1 and DIALCMD2 for MAIL accounts. These fields should hold the modem commands necessary to dial the remote BBS with. These two fields are concatenated (treated as one) when Magnum dials this account. For example: DIALCMD1=ATH0S7=60,DT DIALCMD2=1-818-782-6290 Note the S7=60 portion tells your modem to wait up to 60 seconds for a connection with each dial attempt. AMMO only tries 20 times before giving up. 20 tries at 60 seconds/try = 20 minutes. F) Change all other fields in RED color to whatever is appropriate. Make sure we have access to the message conferences you wish. G) Assign us to a MSGGRP. For example, MSGGRP of 3 means that you'll need to create the file MSG3.GRP in your SESSION DIRectory. If you're NOT using the 'Extended MsgBase' module, the contents of this file should be one ASCII text line as follows: 0 RWL ; This means that we'll have read/write/list access to MsgBase 0. If you ARE using the 'Extended Msgbase' module, give us access to the MsgBases you wish us to have access MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 15-6 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) to. Example: 0 RWL ; 3 RWL ; 157 RWL ; H) Be CERTAIN to change the RMAIL field to Y (yes)!!!! I) Add our Serial# to the AMMO.MAG file in your SESSION DIRectory. If the file AMMO.MAG doesn't exist in your SESSION DIRectory, you'll need to create it. Without it, AMMO/RMAIL is "not installed". This is an ASCII text file with the following format (via example): AGE: 30 1989070000(0):Gilmore Systems Magnum BBS ; BBS name 1989110006 ; \ 1990020045 ; \ ____ Maximum of 500 supported serial#'s 1992030102 ; / accessible to the above as "store 1991050607 ; / and forward" serial#'s. 1989110006(0):TJD Software BBS ; BBS name 1992030102 ; ----> "store & forward" to this serial# 1991020321(22):ABC Corp BBS The first thing you'll notice above is the AGE: keyword. This is an OPTIONAL keyword and can be placed anywhere within the AMMO.MAG file (as long as its on a line by itself): AGE: xxx where xxx is the age (in days) of messages which are allowed to be sent to or received from other systems. For example, if you have: AGE: 20 then no messages older than 20 days will be sent to other systems. Likewise, no incoming messages older than 20 days will be accepted by your system. The age (in days) of a message is determined by its creation date (the date the message was created). This feature is HIGHLY recommended for all Sysops participating in AMMO/RMAIL. The "AGE: xxx" (without the quotes) specification is not limited to appear only once in the file. You may place it on however many lines of your AMMO.MAG file that you wish, each occurrence can have a different parameter. Once this specification appears in the AMMO.MAG file, the age you specify is in effect until another AGE specification appears in the file, or for the remainder of the file (whichever occurs first). You can even have a different AGE parameter for every serial# if you wish by placing an AGE statement on the line immediately before a particular serial#. One excellent example of how this feature would be of great significance is when you're setting up a new AMMO account: without the use of the AGE field, your first link with a new AMMO account will receive your entire messagebase(s). You may want to limit the outgoing messages to this new MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-7 account by, say, 60 days. Also, for informational purposes, a parameter of zero (ie: AGE: 0) turns off this feature (ie: no age calculations will be performed). SERAIL#'s: After the optional AGE: keyword in the above example, the serial#'s of other systems are specified. The number in parens indicates which msgbase incoming mail from this serial# will be placed. If you are NOT using the optional "Extended MsgBase" module, then this number MUST be 0. The format of the file is simple: Direct_Link_Serial_Number(MsgBase):BBS NAME ; Optional Comment Optional_Store_and_Forward_Serial_Number_1 ; Comment Optional_Store_and_Forward_Serial_Number_2 ; Comment Optional_Store_and_Forward_Serial_Number_N ; Comment Next_Direct_Link_Serial_Number(MsgBase):BBSNAME ; Comment etc, etc, etc Note that normally any 'store-and-forward' links should also appear as either a 'direct-link' somewhere in the file, or should also appear as a 'store-and-forward' link under more than one 'direct-link'. Mail coming in to your BBS from whatever Serial#, will be placed in the MsgBase specified in parenthesis next to the serial# above. However, if a 'reply' to a message is coming in, it will be placed in the same MsgBase and conference area as the message it's replying to. If any 'store-and-forward' serial#'s are listed below a 'direct-link' serial number (but before the next direct-link serial#), messages for those serial#'s will be sent to the direct-link serial# when connected. For example, if you're in New York and you have a 'direct link' with us, then you might consider having 'direct links' with other Magnum systems in your area. You could then list those serial#'s as optional store-and-forward numbers under the direct link with our serial# so that users of those serial#'s could send us mail via your BBS. Remember, a 'direct-link' entry in the AMMO.MAG file consists of a 10-digit serial#, immediately followed by a MsgBase in parenthesis, which is immediately followed by a colon (:) character, which is immediately followed by descriptive text of the BBS. A 'store-and-forward' link entry (a serial# in which messages are stored on your BBS and then forwarded to a 'direct-link' serial#) is simply a 10-digit serial# (and nothing else) which is listed below a 'direct-link' serial# (and before the next 'direct-link' serial#). Each 'direct-link' serial# can be followed by as many as 500 'store-and-forward' serial#'s. When a 'direct-link' serial# is connected with your BBS for AMMO RMAIL exchange, the 'direct-link' serial# receives all mail targeted for its serial# along with all mail targeted for the 'store-and-forward' serial#'s listed below it. Any mail sent to the 'direct-link' serial# (including those of 'store-and-forward') will be marked by AMMO as being "sent" on your system, and the 'store-and-forward' messages will be considered "unsent" MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 15-8 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) on the receiving system until they reach their target BBS serial#. IMPORTANT: With the exception of 'replies', Incoming mail will be placed in the MsgBase you provide in parens! The actual Conference Area the message will be placed in will be the same as the conference area on the sending machine (regardless of which MsgBase it's coming from). Therefore, links should have access to ALL conference areas of your incoming MsgBase (A-Z), and ALL conference areas in your MsgBase (whichever it is) should be defined and used! FOR THIS REASON WE STRONGLY RECOMMEND THE 'EXTENDED MSGBASE MODULE'!! NOTE: During mail processing, OUTGOING mail will be named RMnnnnnn.ZIP (in the RMAILOUT directory), and INCOMING mail will be named RMnnnnnn.ZIP (in the RMAILIN directory). Note that nnnnnn will be the userid of the mail account on YOUR system. INFO: The RMAILOUT and RMAILIN directories are created for you automatically. These are subdirectories of the main MSG DIRectory. WARNING: NEVER, NEVER, NEVER GIVE OUT AMMO MAIL ACCOUNT INFORMATION TO ANYONE BUT THE SYSOP OF A MAGNUM SYSTEM YOU'RE ESTABLISHING A DIRECT LINK WITH!! To start an AMMO exchange of RMAIL: ----------------------------------- There are two ways of starting an AMMO exchange of RMAIL with any particular link you're set up for: 1) Manually 2) Automatically With the manual method, enter the command at the MBBS.EXE "Command => " prompt: * RMAIL node:id Let's suppose you've established a mail account with us. Suppose that the ID number on your system that you've set up for us was /999. Now suppose that you want Node 2 on your system (or any other MODEM node on your system) to perform an AMMO RMAIL exchange with us. The actual command you'd issue is: * RMAIL 2:999 The rest is automatic! You can walk away at this point. Your system will gather up all messages targeted for our BBS and then call our BBS using node 2's modem with the DIALCMDx information in account /999. Your system will try up to 20 times to get a connection with our BBS before it gives up. If it gets connected, it will log on automatically and our BBS will gather all mail targeted for your system. The two systems will then exchange mail, hang up, process mail, and end the session. Note that either of our systems can call the other at any MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-9 given time. To automate the "* RMAIL Node:ID" command, simply put it in your MBBS.ACE file to execute at whatever days you wish, and as many times as you wish. See the chapter entitled "ACE - Magnum's Event Handler". Typically, busy systems need to set aside times designated for mail, otherwise the mail account may never make it online! This can be accomplished with the "x CALLS MAIL" command to accept calls from mail accounts on node x - all other callers (user accounts) will be denied access. To revert back to normal operations, the command "x CALLS ALL" must be issued for node x. In this normal mode of operation, Magnum will accept calls from both Users and Mail accounts. Once again, this command can be placed in your MBBS.ACE file. After a mail caller calls, processing of mail begins immediately after their id and password have been successfully entered. All usual display of .BBS files are omitted, and "Press Enter..." prompts are omitted. The entire process is automated between the two machines. However, there is one .BBS file which, if exists, will be processed/displayed. This file is RMAIL.BBS (in the SESSION DIRectory) if it exists. This file serves no real purpose at this time, but is reserved for future expansion. INFO: The "* RMAIL node:id" command actually starts a LOCAL session. You must NOT be online on the local (console) node at the time of this command! AMMO is online on the local (console) node when the RMAIL command is given. It uses the modem and configuration for the 'node' number you supplied, therefore, no one must be online on node 'node'. RMAIL only works with 'nodes' (STARTUP.n) that were configured as 8 databits, 1 stop bit, No parity. AMMO assumes a modem with the "AT" command set, although this may not be necessary for proper operation. Entering Messages to Users on Other Systems: -------------------------------------------- There are 3 ways to enter a message to users on other systems: 1) Use the $ character at the ADDRESSEE prompt (who is msg to?). Enter Serial# at the Serial# prompt (? provides serial# list). Enter /ID of user at that serial#. 2) Use the $ character at the ADDRESSEE prompt (who is msg to?). Enter BROADCAST at the Serial# prompt. Enter ALL or SYSOPs. This method will broadcast your message to all systems allowed to exchange messages with the system you entered the message on. In turn, these systems will broadcast your message to all systems allowed to exchange messages with their systems, etc. This will get your message onto many systems very quickly. 3) When reading a message from a remote system/user (FROM field starts with the $ character), choose [R]eply at the message MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 15-10 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) disposition prompt. Simply reply to the message as you would any other message. Tech Note: ---------- With the advent of 'remote mail' capabilities in conjunction with the ability for the sysop to select the MILC command character for their message system, you may be wondering if messages using MILC commands on one system are executable on other systems... especially if the two systems are using different MSGMILC command characters! The answer is YES. Regardless of the MSGMILC command character, any message that works on the originating system will also work on any other system when transferred via remote mail. However, the commands that are available (executable) in a remote message (one received from another system) are limited to the MILC commands you specify in the MILC_CMDS parm of your STARTUP.n file for that node. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Outside Mail Page 16-1 The QWK Message format: Offline Messaging, QWK 'Networking' The QWK Message format seems to be "the" message standard for BBS's. There are many QWK "readers" (programs that let you read and respond to or enter messages offline at your own leisure) available for DOS, OS/2, Windows, NT, and other operating systems. Almost any BBS you call which offers downloadable applications includes a downloadable QWK reader for whatever OS you're using. Originally QWK was developed for offline messaging (ie: create a QWK packet online, download it, read/reply/create messages offline with a QWK reader, then upload your REP [response] packet back to the BBS for processing & posting to that BBS's Message system). With the exception of Magnum BBS software, all other BBS software makes the online user WAIT (and wait, and wait) for the BBS to compile a downloadable QWK message listing specific to that user. Since Magnum executes its QWK processing programs as RJE (in the background) the user is not forced to wait... the user can go on to do anything else on the BBS or even log off - the background QWK programs will continue to process the user's job until they complete! For normal user-based offline reading/writing, everything can be accomplished for the online user by entering Magnum's "[R]JE Menu". The QWK standard has been expanded to interchange messages from one BBS to another (unlike BBS's and even unlike Operating Systems). Some of the more capable BBS software (still DOS based at the moment) has 3rd party or built-in QWK programs to handle the processing of message interchange between unlike BBS systems. Magnum BBS includes the necesssary programs to accomplish QWK-based message interchange with ANY BBS that offers QWK-based message interchange. The MSGLIST.EXE and RJEQWK.EXE programs (rje_dir) are the programs which Magnum uses for QWK production of .QWK packets and processing of incoming .REP packets. These two programs can do much more: they can be used to exchange QWK messages to/from unlike BBS's or amongst Magnum systems (although Magnum's AMMO/Rmail is more suitbale for Magnum-Magnum systems). QWK message interchange between different systems is by convention, a manual method but with some work you could automate the process with terminal programs that employ a scripting language. With the modifications and enhancements added to MSGLIST.EXE and RJEQWK.EXE, you will be able to operate a QWK-based message network either as a HOST and/or a NODE. Either way, create a new account (logon as a new user with an appropriate name of your choosing), log off, then log back on as Sysop. Go into the Sysop menu, pull up the new account and change the TYPE parm to something other than U or M (we suggest Q for QWK, but you can use anything you wish other than U or M). Give this account access to any msgbases/conference areas you want this account to have. If operating as a Host, have the 'node' BBS Sysop call in under this new account to create a .QWK packet for himself or to upload a .REP packet. If operating as a Node, create a .REP packet under this ID, rename the .rep to the appropriate name, then call the Host BBS and MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 16-2 Outside Mail The QWK Message format: Offline Messaging, QWK 'Networking' upload the .REP and create/download the .QWK packet, use RJEQWK.EXE to process the .QWK packet you just downloaded from the host. Create a new account as above for each Host or Node you wish to exchange messages with. DO NOT CONFUSE these new accounts with the 'outside mail' account which you may have created with v8.01b of Magnum. An 'outside mail' account is NOT an account in which anyone or thing is going to be logging on to (although its certainly possible to log on as the 'outside mail' account). There is only ONE 'outside mail' account as specified in your STARTUP.n file(s). Because EVERY user name within a Magnum system needs to have an ID number associated with it, people who are NOT in a Magnum USER Database do not have an ID number on your system - that's where the 'outside mail' account comes into play - any messages to or from someone who's not in your USER Database will automatically use the ID number of the 'outside mail' ID - there's no limit as to how many different names can be used - they're all associated with the 'outside mail' ID. Hints: - RJEQWK.EXE expects its input in the WORK_DIR specified within the MBBSINIT.n file being used (the compiled version of the STARTUP.n file). - MSGLIST.EXE creates .QWK or .REP packets using the standard Magnum RJE naming conventions (ie: Uid@n.QWK or Uid@n.REP). These should be renamed appropriately (they're placed in \magnum\rje). - Refer to the file QWK.MAP (which was placed in your SES_DIR) for a more detailed synopsis. This entire file (until you modify it) is one large comment. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Outside Mail Page 16-3 The "Outside Mail" ID Every user on a Magnum system requires a User ID. The exception is the "Outside Mail" ID which is an ID, but does not belong to any particular user. Use of the "Outside Mail" ID is simply a user's way of telling Magnum (or Magnum's way of telling you) that a message to/from this ID is a message to/from someone who is "outside" of this particular Magnum system. For example, if you exchange QWK packets with Congress (as a hypothetical example), to enter a message to Sonny Bono or Newt Gingrich or any other person on the Congress BBS, you must enter a message to the "Outside Mail" ID (if you're doing this online, you'll then be prompted for the actual name of the person you're sending the message to). If you're entering the message offline (through a QWK reader), simply supply the person's name (Sonny Bono or Newt Gingrich for example); when Magnum processes an incoming QWK packet with a message to/from someone not in Magnum's User Database, it assigns the Outside Mail ID as the ID for that person, but retains the person's real name which will be relayed to the other (outside) system where that person really is. Its recommended you create a NEWMSG.BBS file (DSP_DIR) to inform your users of the Outside Mail ID for message entry to users not in your user database. If you haven't created an OUTSIDE MAIL ID yet, you may do so by logging onto your BBS (via the console node) as a new user by the name of OUTSIDE MAIL, then logging off. Write down the ID assigned to this account, and log on as the Sysop. Go into the Sysop menu, User Database area; the Sysop record (ID /0) will be the first to come up. Enter /nnn (where nnn is the ID number) of the Outside Mail ID that you wrote down; the Outside ID account will come up. Change the Account Type to O (for Outside mail), change all msg parameters (MsgGroup, MSG_x_AREAS, etc) to allow access to ALL message areas and bases, then log off. Shut down the BBS, change the OUTSIDE_MAIL_ID to the ID of the outside mail account for all STARTUP.n file(s) and change the ALLOW_OUTSIDE_MAIL parm to N. Compile (MAKEMBBS.EXE) and then restart your BBS. You are now set up for outside mail exchange. The account TYPE for any user record can be any character or letter you wish. Up until Magnum v8.xx, only two account types existed: U for USER accounts, and M for MagnumMAIL accounts. These two types are still in use and always will be. However, in preparation for outside mail exchange with other mail formats, you can now assign an account type of other than U or M. For example, to exchange mail with a QWK 'net', you might assign a certain account for that purpose and classify it's type as Q (for QWK), or I (for Internet). Use letters such as Q for QWK 'net' accounts, and I for Internet. This release will support QWK 'netmail'. If an account other than U or M logs on, Magnum will now look in your SESSION DIRectory for (and display) the file ACCTTYPE.x (where 'x' is the account type) if it exists. This file can contain MILC commands to start an RJE or child (door) process to perform whatever it is you wish. This file displays after logon and BEFORE entry into the main menu. To set up a QWK 'net' account, you must log on via the console as a new user, providing a mnemonic name such as "QWK GLOBALNET" or "GLOBALNET QWK" for example. Choose a default xfer MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 16-4 Outside Mail The "Outside Mail" ID protocol such as Zmodem. After the new account has been established, log off and then log on as Sysop (/0). Go into the Sysop menu and pull up the user record for the new account and change the account TYPE to Q. You should also create or modify the display file NEWMSG.BBS (in your DISPLAY DIRectory) to inform your users of ID's to/from outside mail networks (ie: enter a msg to ID /nnn for GLOBALNET, /yyy for ALTERNET, etc). NOTE: Account types other than U (user) will not invoke the standard HELLO?.BBS files or other display files prior to entering the main menu after logon, nonstop display is automatic, and PRESS ENTER prompts are bypassed. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Internet E-mail Page 17-1 General Info and Setup INTERNET E-MAIL --------------- To set up your Magnum BBS system for Internet E-mail capabilities, you must first have: 1) An Internet Service Provider (we recommend "Info Access Technologies", also known as Holonet). Voice: (510) 704-0160, Modem: (510) 704-1058. 2) UUCP Domain Name Service (this takes about 3 weeks for your Internet Service Provider to set up). UUCP Domain Name Service means that your BBS will be known as somename.com (for us, its gilmore.com). The users on your BBS will be known as someuser@somename.com (using our site as an example: joe@gilmore.com, susan@gilmore.com, postmaster@gilmore.com, etc). 3) Our optional MAGUUCP.EXE program. Once you have the above set up, you will now be able to implement the Internet E-mail capabilities of Magnum BBS as follows: 1) First, you'll need our optional MAGUUCP.EXE terminal program. This is NOT included with your Magnum BBS system and is available for purchase from Gilmore Systems. 2) If you haven't set up an "OUTSIDE MAIL" account, you will need to log onto the system (from the console) using OUTSIDE for 'first name' and MAIL for 'last name' (don't use a middle name). Once the system has added 'OUTSIDE MAIL' as a new user, log off! Jot down the ID number for the new OUTSIDE MAIL account. NOTE: If you already have an OUTSIDE MAIL account set up, skip to step 3. 2a) Log on as Sysop. Go into the Sysop menu, USER Database Area. Pull up the account for the OUTSIDE MAIL ID that you just created. Change the TYPE parm (2nd line from top of screen) to type O (O is for OUTSIDE MAIL). Increase the security level to that which has access to all of the message bases and message areas that you wish this account to have access to. Change the MSG_?_AREAS (near bottom of screen) accordingly. If you have the Extended Msgbase module and are using MSG GROUPS, change the MSGGRP parm accordingly. 2b) Shut down your BBS (* endnow) and edit all of your STARTUP.n files such that the OUTSIDE_MAIL_ID: parameter reflects the id number of this new OUTSIDE MAIL account. Example: if your OUTSIDE MAIL account id is /1407, then you should provide this as the parm as follows: OUTSIDE_MAIL_ID: /1407 3) Shut down your BBS (* endow) and edit all of your STARTUP.n files as follows (changing the following parms): MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 17-2 Internet E-mail General Info and Setup INTERNET_DOMAIN_NAME: gilmore.com (this will be YOUR domain name, like ibm.com or xyzcorp.com). INTERNET_TIMEZONE: PST (PST=Pacific Standard Time, PDT=Pacific Daylight Time, EST=Eastern Standard Time, MDT=Mountain Daylight Time, CST=Central Standard Time, etc). ALLOW_OUTSIDE_MAIL: Y Save the changes and recompile the STARTUP files (makembbs.exe). Restart your BBS. 4) Log on (* logon) as a new user using the account name EMAIL ACCOUNT (EMAIL for first name, ACCOUNT for last name). After this new account id is added, log off! Log on (* logon) As SYSOP (/0) and go into the Sysop Menu, USER Database Area. Pull up the account for the id number of the EMAIL_ACCOUNT. Change the account TYPE (2nd line from type) to E (for E-MAIL). Change MSG_?_AREAS according to the areas you wish this account to have access to. Change the MSGGRP (If you're using GROUPS and you have the Extended MsgBAse Module) accordinly if desired. IMPORTANT: Change the LEVEL (security level) to that of the security level of the SYSOP_MAIL_LVL parm in your STARTUP files. This is important because this account needs to be able to read PRIVATE mail (this is only allowed with a security level of what you have for SYSOP_MAIL_LVL or greater). You can even give it a level to match that of the Sysop if you wish. This is NOT a user account, its an EMAIL account! Once the changes are made, log off. 5) If you haven't done so already (and assuming you have the optional MAGUUCP.EXE program), set up MAGUUCP.EXE. Make note of the directory name you're installing this program into (ie: d:\maguucp) Follow the directions supplied with MAGUUCP.EXE. NOTE: SEE STEP 9 (below) FOR OUR SETUP. 6) In your PGM_DIR (ie: d:\magnum\pgm_dir), create a command file by the name of INTERNET.CMD with your text editor. The contents of the file are: d: cd \magnum\pgm_dir d:\magnum\rje_dir\msglist mbbsinit.3 NNN * u y * * email.out e* cd \maguucp maguucp #NN cd \magnum\pgm_dir MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Internet E-mail Page 17-3 General Info and Setup emailin mbbsinit.3 NNN d:\magnum\ses_dir\email.prm echo N active >tmp.ace exit - In the above, the first line is the drive letter of the drive that your Magnum BBS is installed on (your \magnum\pgm_dir). - The second line changes the directory to your \magnum\pgm_dir. - The third line executes the msglist program. The NNN parm should be the ID number (without the / character) of the OUTSIDE MAIL account that you created in step 2. If your drive letter is not d:, change it to the drive letter that your \magnum\rje_dir is on. We're assuming that you're using node 3, therefore we've supplied mbbsinit.3 on this line. Change the 3 to whatever node you'll be using for your MAGUUCP program. - The fourth line changes to the directory that you installed your MAGUUCP program in (assuming same drive letter as that of your Magnum system... if different, insert a line before this containing the driver letter that its on followed by a colon [ ie: c: ] ). - The fifth line invokes the MAGUUCP program to call your Internet Service Provider (replace the NN with the dialing directory entry for your Internet Service Provider; if its entry #4 for example, you'd supply: maguucp #4). Make sure you've set up your script file for MAGUUCP.NN (or MAGUUCP.4 using our example) as provided in the MAGUUCP documentation. - The sixth line changes back to your \magnum\pgm_dir (assumes that your \magnum\pgm_dir is on the same drive as \maguucp; if it isn't insert a line containing the drive letter of your \magnum\pgm_dir followed by a colon [ ie: c: ] ). - The seventh line processes incoming email and places it in the proper areas of your Magnum BBS system. Change the NNN to reflect the id number (just the number, no / character) of the OUTSIDE MAIL account (same as in line 3). If the drive letter of your \magnum\ses_dir is not d:, change it to the drive letter that your \magnum\ses_dir is on. Create the file EMAIL.PRM in your \magnum\ses_dir with the following contents: headers: n msgbase: 0 area: a Where the 'headers:' parm can be one of N (no headers), Y (all headers), or P (partial headers). If you choose N, incoming mail text will look like it always does. If you choose Y, incoming mail text will include all of the headers including routing information of all the systems that the mail went through before arriving at your system. If you chhose P, then all headers OTHER than routing information will be shown. - The eigth line restarts the node that was shut down (made inactive) in order to use the modem for MAGUUCP. Replace the N with the node number of the node that was shut down (made inactive). - The ninth (last) line exits the command file. 7) Modify your \magnum\pgm_dir\mbbs.ace file (or create it if you don't have one) with the following commands (we're going to use node 3 for the node to be shut down in our example, you should MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 17-4 Internet E-mail General Info and Setup replace this with the node number you wish to use for your system). We're also assuming that your system will be calling your Internet Service Provider at 02:00 (2 AM) every day: 0123456,01:00,3 shutdown 02:00 0123456,02:01,"start internet.cmd",nowait If you wish to have your system call more than once/day, duplicate the above two lines changing 01:00 to one hour before wishing to shut down the node, change 02:00 to the time you want the node shut down, change 02:01 to the time you want maguucp started. 8) In your STARTUP files prior to step 3 above, if your parm to the ALLOW_OUTSIDE_MAIL was N, you'll need to write a .mex program to change the users in your USER database to allow them access to outside mail. The .mex program should be created in your \magnum\pgm_dir with a name of UPDT.MEX (or something similar). The contents of the file would be: #CONFIG_FILE: mbbsinit.1 #LOG_FILE: nul #DATABASE: user #START @outside_mail = true #STOP The above simple .mex program will change all users to allow them access to outside mail. If you wish to have only a certain security level or higher to have access (say, level 100 for example), change the program statement (between #START and #STOP) to: if(@level >= 100) { @outside_mail = true } Run the program: MBBSEXEC UPDT 9) For setting up the MAGUUCP scripts, first make certain you've made a dialing directory entry for your Internet Service Provider. Lets Assume this is entry #4. Create the file MAGUUCP.4 in the same directory that your MAGUUCP.EXE program resides in. The contents of MAGUUCP.4 will look similar to the following (assuming you're using Holonet as your Internet Service Provider): set caller_hostname gilmore set called_hostname holonet set workdir d:\magnum\work_dir\3 set uucp_protocol g whenever "CONNECT" send "\13\~\~holonet\13" MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Internet E-mail Page 17-5 General Info and Setup whenever "HoloNet Member Name" send "cgilmore\13" waitfor "assword:" send "mypassword\13" waitfor "erminal" send "uucp\13" - In line one above, the caller_hostname is set to our UUCP domain name (without the .com). - The second line sets the called_hostname to holonet (the Internt Service Provider). - The third line matches the work_dir defined in the STARTUP.3 file because we've used mbbsinit.3 (the compiled startup.3 file) in our example in step 6 above. All incoming and outgoin email temporary storage is held in this work directory. - The fourth line sets the UUCP protocol to g. Note that MAGUUCP currently has 6 of the UUCP protocols coded: e = not supported by Holonet, not tested as of this writing. f = supported by Holonet and nearly every other Internet Service Provider. g = the standard (and default) uucp protocol supported by all uucp packages. t = supported by Holonet if using uucp-1.06 as your terminal type. T = Same as t but for uucp versions less than 1.06 (ie: if you supply uucp as your terminal type instead of uucp-1.06). Note that uucp-1.06 works with Holonet, but may not work with other providers. If you have a different provider, use uucp instead of uucp-1.06. y = Supported by Holonet using uucp-1.06. This is a NEW protocol, so your provider may not support this yet). Note that when we refer to uucp-1.06 above, it refers specifically to a UUCP implementation known as Taylor UUCP v1.06. - The fifth line looks for the CONNECT string from your modem (make sure you're using Verbose modem codes [ ie: AT V1 ] ) and sends holonet as the name to connect to. This line is not needed if you're calling Holonet directly at their Berkely, CA number. It is needed if you're calling via a local access telephone number. - The sixth line answers the "Holonet Member Name" prompt with cgilmore. Change this to your member name (your Internet Service Provider will provide you with one). - The seventh line answers the "password" prompt with your password. Change the mypassword string to your password. Note that the beginning P of Password is intentionally absent because it may appear in upper or lowercase, and we need to match this exactly. - The eigth (last) line answers the "terminal" prompt with the type of terminal you wish. Note that the beginning T of Terminal is intentionally absent because it may appear in upper or lowercase, and we need to match this exactly. The rest will be automatically handled by MAGUUCP, and when MAGUUCP finishes, the INTERNET.CMD file which started it will then start the EMAILIN.EXE program to process the incoming mail. USING E-MAIL: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 17-6 Internet E-mail General Info and Setup ------------ Users on your Magnum BBS can enter messages to anyone on the Internet by entering a new message (when the prompt asks for the addressee (ie: /ID) they may either enter the id number (/nnn) of the OUTSIDE MAIL account, or the word EMAIL. Either way result in the following prompt: MAIL TO "OUTSIDE MAIL" (y/n) -> _ When they verify the above promopt with a Y response, the system will then issue the prompt: Name of Addressee => _ They can now supply any Internet e-mail address. To reach a user on CompuServe for example, they con supply 11111.333@compuserve.com (where 11111.333 is the user's compuserve id who they're trying to reach). All incoming e-mail is placed into one area of one messagebase as you specified in step 6 above. Depending on the parms you give to the msglist.exe program, mail can be sent from any msgbase/area on the system, but we suggest you have your users limit internet e-mail to the msgbase and area that you speficied in step 6 above. As of this writing, Internet E-mail is supported. This includes messages entered on your system with "attached files", and any incoming messages with "UU Encoded" files (they'll automatically be converted to "attached files" when added to your message base). Note that you'll need OS/2 versions of uudecode.exe and uuencode.exe in your system path (you could place these in your \magnum\pgm_dir). As of this writing, USENET NEWSGROUPS are NOT supported, and will be ignored and discarded if any news messages come in via MAGUUCP. Future releases will support UseNet NewsGroups. NOTE: if you're having any problems with the 'g' protocol, try using one of the other protocols such as 't' (or 'T') or 'f'. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Internet E-mail Page 17-7 EMAILIN.EXE parameters EMAILIN.EXE: ----------- This program processes incoming Internet e-mail (from MAGUUCP.EXE) and places it into the appropriate Magnum BBS message base/area. Any messages containing uuencoded files will be automatically uudecoded and converted to an 'attached file' (requires an OS/2 version of uudecode.exe to be in your system path). Note that MAGUUCP.EXE is an optional module, and is not included with Magnum BBS. The Syntax of this program is: EMAILIN mbbsinit.x id parmfile Where:-EMAILIN is the EMAILIN.EXE program. -mbbsinit.x is the complete filespec of the mbbsinit.x file to use. NOTE: x is the node# -- make certain that this mbbsinit.x file's WORK_DIR parm matches that of the WORKDIR parm of your MAGUUCP.n file used for dialing your Internet Service Provider! This is the work directory that EMAILIN.EXE will look for incoming mail (MAGUUCP.EXE places incoming mail into the WORKDIR parm specified in your MAGUUCP.n file). -id is the id number for the account running this program. -parmfile is the complete filespec of the parameter file (email.prm); we suggest placing (creating) this file in your \magnum\ses_dir. The parameter file (email.prm) is an ASCII text file which you create with a text editor. The format of the file is as follows: - Any blank lines are ignored. - Any line starting with the ; (semicolon) character is a comment line. - Any ; (semicolon character anywhere on a line starts a comment). - All comments end at the end of the physical text line. MSGBASE: 0 ; indicate which msgbase to place incoming mail into. AREA: E ; indicate which area of above msgbase for incoming mail. HEADERS: N ; parm can be one of: N Don't save header info (default) Y Save header info in msg text P Partial save of header info LISTSERV: info = d:\somedir\infofile.txt LISTSERV: help = d:\somedir\helpfile.txt ALIAS: review.board = 12 ALIAS: votes = 256 The MSGBASE, AREA and HEADERS keywords are mandatory. All others are optional. Up to 250 LISTSERV entries can be accomodated. The way a LISTSERV entry works is as follows: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 17-8 Internet E-mail EMAILIN.EXE parameters Using the above example (LISTSERV: info = d:\somename\infofile.txt), incoming mail addressed to info@company.com (the @company.com portion is stripped out, making just "info") is checked against your LISTSERV entries in your parm file. If a match on "info" is found, it sends the filespec (that appears on the right of the "=") as a message to the sender (requester) of the message. If you wish to attach a file as part of the message, you may uuencode the file and concatenate it to the end of your message. This serves as an automated response system, where (by example) anywone wishing information about your company may send mail to info@yourbbs.com and automatically get a response back without you having to worry about it. A log of these automated responses will be kept under the filename of "listserv.log" in your SYSOUT directory. Up to 500 ALIAS entries can be accomodated. The way an ALIAS entry works is as follows: Using the above example (ALIAS: anonymous = 4), incoming mail addressed to anonymous@company.com (the @company.com portion is stripped out, making just "anonymous") is checked against your ALIAS entries in your parm file. If a match on "anonymous" is found, it replaces it with the id number (that appears on the right of the "=") as a message to id4@company.com (using the above example). Although the users of your BBS can change their own name using the '[E]nivronment' section (#27 of the Environment menu), they may also request that they be knwon as something else as well (its up to the Sysop to supply alias names via the parm file). This way, any user can be known by multiple names. NOTE: Only Incoming mail can be routed to an alias name. Outgoing mail (including a reply to a message addressed to an alias name) will always bear the user's real name (ie: that supplied by Magnum [ id4@company.com ], or by the user's Environment name [ jsmith@company.com ] ). The purpose of alias names are for users to submit mail to, but should not expect replies. Uses of alias names are for people to submit reports to, votes, grievances, or any other type of mail where the person using the alias name does not wish to reveal who they really are. People using alias names should NOT reply to incoming mail (any replies will reveal their real name). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems General and Closing Remarks Page 18-1 General Remarks If you're using either the Extended FileBase or the Extended MsgBase module(s), be aware that each user's pointer file(s) are kept in a ZIP'd file in the USER_DIR by the name of dpID.zip where ID is their user id number. Within these dpID.zip file(s) are the following compressed pointer file(s): mpID.ptr and/or fpID.ptr. Uncompressed sizes of these file are: mpID.ptr = 66300 bytes fpID.ptr = 27540 bytes Total if using both extended msg and file base modules: 93840 bytes. These pointer files are uncompressed for a user during their online session (up to 93840 bytes), and then compressed back into the dpID.zip file after their session ends. The uncompressed sizes given above are constant regardless of whether you're using 1, 2, or ALL of the 255 extended bases. IMPORTANT: The amount of disk space the dpID.zip file takes up depends solely on the version of the ZIP program you use. For example, the original PKZIP2.EXE compresses these files down to about 1.5 Kbytes during our testing. However, the latest ZIP.EXE from the InfoZip people compresses these same files down to about 400 bytes (nearly 4 times less space used than PKZIP2.EXE). This saves about 1100 bytes per user, very significant! During our testing using 3 extended filebases and 1 extended msgbase, the average compressed (zip'd) size was 233 bytes. You can obtain the latest version of InfoZip's ZIP.EXE and UNZIP.EXE by downloading the following files from our FileBase 0: UNZ512X2.EXE - Self-Extracting File (when finished, copy UNZIP.EXE to your EXT_DIR ZIP201X2.ZIP - Unzip with UNZIP.EXE above (when finished, copy ZIP.EXE to your EXT_DIR Note that the above are 32-bit programs, meaning they will NOT run under OS/2 1.x, you will need OS/2 2.x or 3.x (Warp). If you created a COMPRESS.LST file in your SES_DIR, you will need to modify the .ZIP: entry as follows (create the file with the following contents if you do not have a COMPRESS.LST file): .ZIP: C=ZIP.EXE -u %s D=UNZIP.EXE -oqjC %s L=UNZIP.EXE -v %s T=UNZIP.EXE -t %s K=ZIP.EXE -z %s MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 18-2 General and Closing Remarks General Remarks Note that upper/lowercase is important and must appear exactly as above. When logging on locally (via the console), or snooping on a remote session, you may see an error message on your screen "SYS1816: The batch file cannot be found". This is normal, and will NOT be seen by your remote callers. MSESSION.EXE creates a .cmd file and calls it, the command file deletes itself when finished, but OS/2 thinks there may be another command in the file... since the file deleted itself, OS/2 emits the SYS1816 message. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems General and Closing Remarks Page 18-3 Closing Remarks Congratulations! You've just completed reading the documentation for the Gilmore Systems Magnum BBS System for OS/2. We hope that you'll have many years of ongoing satisfaction with this product. If you have any problems, please leave them in the form of a "[C]omment to Sysop" or message on our BBS at 818/782-6290, or e-mail us (sysop@gilmore.com) and we will have a response for you usually within 24 hours (weekends and some holidays excluded). ALL TECHNICAL SUPPORT QUESTIONS AND PROBLEMS WILL BE HANDLED EXCLUSIVELY VIA OUR BBS AT (818) 782-6290 OR VIA E-MAIL (SYSOP@GILMORE.COM). IF YOU CALL ON OUR VOICE LINE WITH A TECHNICAL SUPPORT QUESTION OR PROBLEM WHICH REQUIRES US TO CALL YOU BACK, WE WILL CALL YOU BACK COLLECT! HAVE YOUR SERIAL NUMBER READY (YOU WILL BE ASKED FOR IT). We've set up a special section on our BBS for Magnum Sysops (file area 'S' and message conference area 'S'). This will enable you to converse with other Magnum Sysops, exchange ideas and information, ask questions, etc. We encourage regular checking in from time to time. Other Sysops have already wrote some external programs for Magnum which they've uploaded (you can download these anytime). If you wish information on the record layouts for Magnum's databases, please inquire within - we encourage 3rd party development, but do not support it (3rd party developers must support their own products). So far, Magnum BBS will run with almost any modem. Your modem should be capable of hardware flow control (CTS/RTS) and your modem cable must have RS-232 pin numbers 4 and 5 wired to carry these signals - some cables are not wired this way. This is especially the case when the DTE baudrate (the speed of computer to modem) is higher than that of the modem's DCE baudrate (the speed of the modem over the phone lines). Some internal modems force the carrier signal high (constantly on) - your modem needs to report carrier to Magnum in a realtime fashion (the true state of the carrier signal - for modems with the "AT" command set, this is usually accomplished with the &C1 command). Your modem must also be configured to respond to the DTR signal - in other words, when Magnum closes the comport, your modem should respond by dropping the line - if your modem uses the "AT" command set, see the &Dn command in your modem's user manual. For modems with the "AT" command set, see the S10 register in order to make your modem drop the connection when carrier is lost. Keeping things in perspective, your modem is your computer and BBS's only link to the outside world. It is important that you not cut corners in this arena. Magnum BBS and your modem(s) have a synergistic relationship and we suggest you use a name brand modem which has been successfully used in the public arena for a long time. See the file MODEMS.TXT in the root directory of your distribution diskette for information on setting up some of the more popular modems. Also on your distribution disk, is a file called MAGNUM.H which are the structure layouts (in C) of the databases used by Magnum (USER, MSG, RJE, FILE, UTILIZ). This file is NOT included with the demo release MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 18-4 General and Closing Remarks Closing Remarks (the database structures are different). With this information you may write your own programs to manipulate the databases used by Magnum. By all means, give us a call if you have ANY questions or concerns about accessing the data in these databases. Should you write programs which actually WRITE to or APPEND to these databases, be sure to adhere to standard record-locking conventions. If you'll be appending to the USER database, give us a call for important information you'll need to know - it's not as simple as just "appending" a record (all other databases EXCEPT the USER database are straight-forward if appending). IMPORTANT CONSIDERATIONS: ------------------------ ALWAYS, ALWAYS have a backup copy of your databases prior to running the MBBSEXEC.EXE program. Any errors (ie: typos, logic, etc) in your .MEX files can destroy your databases! We're running our system such that an "ACE" command starts a .cmd file which copies the databases to a different directory prior to running the mbbsexec.exe program for maintenance. If you're writing a new '.mex' file, you should consider setting up a test system to test it out with - do not experiment on your production system without full backups of the databases! Magnum uses variables @Z0, @Z1, @N0 and @N1 internally when invoking external programs such as pkzip2.exe, pkunzip2.exe, arc2.exe, chkansi.exe, etc... bear this in mind when using the @R1, @Fx and @Qx MILC commands. Be advised that the RJE menu's [K]ill option will only kill the program it started - not any children of that program. IMPORTANT INFORMATION ABOUT COM*.SYS DEVICE DRIVERS: --------------------------------------------------- If you're running OS/2 SE 1.2 or OS/2 EE 1.2 on an IBM PS/2 machine: The COM02.SYS device driver may or may not work with your version of OS/2 1.2. To find out if your COM02.SYS driver is the proper one for your system, execute the following command (comes with the Operating System): SYSLEVEL.EXE After a couple of minutes, you'll get the CSD level. For OS/2 version 1.2 SE, the CSD level should be XR04073 or greater. For OS/2 version 1.2 EE, the CSD level should be XR04084 or greater. If your CSD level is less than the above, the COM02.SYS device driver for your operating system is defective. You can correct the problem by either using the COM02.SYS device driver supplied with OS/2 ver 1.1 or by updating your system to the latest CSD level. Unfortunately, IBM is the only company which supplies CSD (customer service disks) updates which can be obtained by contacting your local authorized IBM dealer. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems General and Closing Remarks Page 18-5 Closing Remarks OS/2 1.2 EE CSD levels WR04097 and WR04098 has a problem in the kernel relating to auto-buffering regardless of whether your UART supports auto-buffering or not! Because the problem lies within the kernel it cannot be fixed by simply replacing the COM0x.SYS or other device driver. The "fix" is one of two options: 1) Go back to a CSD level earlier than WR04097 or 2) Upgrade to OS/2 1.3 EE. Since there will be no more CSD's released for 1.2, the "fix" is to upgrade to OS/2 1.3 EE. OS/2 Version 1.3 As of this writing, IBM OS/2 v1.3 SE and OS/2 v1.3 EE has no known problems. OS/2 Version 2.0 & 2.1 The COM.SYS driver included with OS/2 2.0 and 2.1 is not very reliable, causes system slowdown, and has been known to cause sessions to hang. Unless you're using a Digiboard or Artic card or other intelligent communications coprocessor requiring its own device driver, we highly recommend replacing your COM.SYS (and VCOM.SYS) drivers with Ray Gwinn's comm drivers. Ray's drivers are many times faster, extremely reliable, and work with all machine types (ISA, EISA, Microchannel, etc). As of this writing, the current release of Ray Gwinn's comm drivers are SIO102.ZIP and can be downloaded from our BBS. Read the instructions within for installation information, and by all means, help Ray out with a contribution to his fabulous development efforts. If you find that Ray's drivers work well for you, he sells 4, 6, 8, and 16-port versions of those drivers. DOS DOORS If you're using OS/2 2.1, YES - you can run DOS doors!! A 3rd-party program is available for download from our BBS. As of this writing, download the following two files: MAGFOSS.ZIP & FOSSDM05.ZIP (requires OS/2 2.xx or 3.xx). ZIP Compression Format No matter which version of OS/2 you're using, download UNZIP16.EXE from our BBS, rename it to PKUZNIP2.EXE and place it in your EXT_DIR (or keep the name as UNZIP16.EXE and modify your COMPRESS.LST file accordingly). PK-Ware has NOT (as of this writing) released an OS/2 version of their 2.04G ZIP compression format, this 3rd-party program (UNZIP16.EXE) will solve this problem until they do! Also, be advised that since many users (callers) will be uploading files in this new format, unless you're using UNZIP16.EXE, those files will fail the zip 'Test' automatically performed after upload unless you use UNZIP16.EXE. Additionally, callers uploading messages in the QWK message format (.REP file) will also be using the new format (2.04G) which will require the use of the UNZIP16.EXE program. The sooner you download this program, the better! We are unable to distribute this program with the Magnum system. We have a license to distribute PK-Ware's ZIP utilities, but ironically these utilities are obsolete until PK-Ware releases a new MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page 18-6 General and Closing Remarks Closing Remarks up-to-date OS/2 version of their own utilities! SUMMARY OF IMPORTANT CONSIDERATIONS: From time to time in OS/2 2.1 when a session starts (as an icon), the OS will place the icon for that session directly over an icon for another session. Moving (dragging) that icon out of the way reveals the other icon underneath it. OS/2 2.x doesn't seem to want to display our icon file. To get around this, create the following statements in your MBBS.ACE file: *,1 icon d:\magnum\pgm_dir\msession.ico *,2 icon d:\magnum\pgm_dir\msession.ico . . . of course, you'll need to substitue the path name you're using on your system; and the three dots merely represent additional statements, one for each node you have on your system. In that these are "immediate" commands (read only on startup), you'll need to shut down the bbs and restart it in order for these commands to "take". MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Index Page I-1 - . - .SNP ..................... 9-5, 9-60 - < - <F6> ..................... 5-18 <F7> ..................... 5-17, 7-5 - @ - @# ....................... 4-22 @A ....................... 1-30, 4-3 @B ....................... 4-4, 4-7, 4-33, 4-53 @C ....................... 4-6 @D ....................... 4-10 @E ....................... 4-12, 4-15, 4-16, 4-17, 4-18, 7-41 @I ....................... 4-19, 4-20, 9-3, 9-4, 9-7 @J ....................... 4-21 @K ....................... 4-22 @L ....................... 4-23 @M ....................... 4-24 @N ....................... 4-4, 4-7, 4-19, 4-25, 4-26, 4-27, 4-34, 4-35, 4-48, 4-53, 6-20 @O ....................... 4-7, 4-28, 4-30, 4-47, 7-35 @P ....................... 4-4, 4-33 @R ....................... 4-34 @S ....................... 1-20, 4-36 @T ....................... 4-37 @U ....................... 4-7, 4-38, 4-47, 4-52 @V ....................... 4-42, 4-47 @W ....................... 4-44 @Y ....................... 4-21 @Z ....................... 4-4, 4-5, 4-7, 4-9, 4-19, 4-34, 4-35, 4-45, 4-46, 4-53, 6-20 @\ ....................... 4-49 - A - ACCOUNT TYPE ............. 2-6, 2-7, 4-41, 16-3, 16-4, 17-2 ACE ...................... 2-3, 5-5, 5-11, 5-12, 5-14, 5-21, 6-3, 8-1, 8-2, 8-3, 8-4, 8-5, 8-6, 15-9, 18-4 AMMO ..................... 2-4, 2-5, 6-4, 7-32, 15-1, 15-2, 15-3, 15-4, 15-5, 15-6, 15-7, 15-8, 15-9 ANNOUNCE ................. 1-10, 2-2, 2-17, 5-1, 5-7, 5-8, 6-3, 8-3, 8-4 ANSI-EDITOR .............. 7-13, 7-14 ARQ ...................... 1-36, 1-37, 1-38, 7-21 - B - BELL ..................... 5-1, 5-3, 5-4, 7-5 Blockwrite ............... 5-13 Blog() ................... 9-29, 9-37, 9-38, 9-59, 9-62 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page I-2 Index - C - CALLS ALL ................ 5-15 CALLS MAIL ............... 5-15 CC List .................. 12-1, 12-2 CD-ROM ................... 2-2, 3-5, 3-7, 9-10 CONDENSE ................. 5-12, 5-13, 5-14 CTS ...................... 1-1 Call() ................... 9-29, 9-46, 9-48 Carrier .................. 1-10, 1-15, 1-36, 1-37, 1-38, 2-4, 4-7, 5-1, 5-3, 5-9, 5-10, 6-1, 9-13, 18-3 Chat ..................... 1-17, 1-31, 2-15, 3-3, 4-31, 5-10, 5-17, 6-20, 7-5, 7-6, 13-2 Child .................... 1-10, 1-31, 2-2, 2-6, 2-12, 2-13, 4-31, 4-42, 4-43, 6-1, 6-3, 6-16, 7-10, 7-17, 7-28, 7-40, 7-42, 9-32, 9-53, 9-59, 16-3 Clog() ................... 9-29, 9-38, 9-47, 9-62 Compression .............. 2-4, 2-12, 3-4, 4-40, 6-4, 6-5, 6-6, 6-7, 6-8, 7-2, 7-7, 7-27, 7-28, 9-7, 18-5 Crash Recovery ........... 7-21 - D - DCE ...................... 1-10, 18-3 DOS DOORS ................ 18-5 DTE ...................... 1-10, 1-11, 1-14, 7-8, 18-3 DTR ...................... 1-1, 1-6, 18-3 Door ..................... 2-12, 2-13, 4-16, 11-1 - E - E-mail ................... 1-20, 1-21, 2-2, 2-7, 2-14, 6-2, 7-8, 9-8, 12-2, 17-1, 17-2, 17-3, 17-4, 17-5, 17-6, 17-7, 17-8, 18-3 ENDNOW ................... 1-6, 5-9, 5-10 EQUATE ................... 9-45, 9-56, 9-57, 9-61 ERRLOG ................... 5-15 Environment .............. 4-10, 4-46, 6-1, 7-28, 17-8 Error Correction ......... 4-40, 9-13 Exit() ................... 9-29, 9-30 External File Compression 2-4 External file compression 2-4 Extract() ................ 9-54, 9-55 - F - FAXMODEM ................. 1-38 FILE MENU ................ 1-28, 1-29, 1-32, 2-10, 3-4, 4-8, 6-12, 6-13, 6-15 FILE_ID.DIZ .............. 7-24, 10-2 FORCEOFF ................. 5-3, 5-4 FRAMECOLOR ............... 5-15 FSTART ................... 9-60, 9-61, 9-62 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Index Page I-3 FSTOP .................... 9-60, 9-61, 9-62 File group ............... 4-41, 9-7, 14-1, 14-2 Form Letters ............. 9-1, 9-35 - G - Goto() ................... 9-48 - H - Handshake ................ 1-36 - I - Icon ..................... 2-3, 5-3, 5-5, 5-20, 18-6 If() { ................... 9-62 Indirect addressing ...... 4-49, 4-52, 4-53, 4-54, 4-55, 9-43, 9-44, 9-54, 9-64 Initialization ........... 1-12, 3-2, 4-34, 9-2, 9-14 Input() .................. 9-29, 9-39, 9-47 Internet ................. 1-20, 1-21, 2-2, 2-7, 2-14, 4-41, 4-43, 6-2, 7-8, 7-36, 9-8, 12-2, 16-3, 17-1, 17-2, 17-3, 17-4, 17-5, 17-6, 17-7, 17-8 Internet Service Provider 17-1, 17-4 - L - LAN ...................... 1-3, 1-7, 1-9, 1-11, 2-2, 2-3, 7-5, 7-39, 10-1, 13-1, 13-2, 13-3, 15-2 LINE-EDITOR .............. 7-15 LOCKOUT .................. 5-6, 7-16 LOGOCOLOR ................ 5-15 LOGON .................... 1-5, 1-7, 1-19, 1-26, 2-4, 2-6, 2-7, 2-10, 2-17, 3-2, 3-3, 4-17, 4-31, 4-36, 5-1, 5-5, 5-7, 5-8, 5-14, 6-2, 6-3, 6-4, 6-8, 6-9, 6-11, 6-14, 6-17, 7-1, 7-2, 7-3, 7-18, 7-28, 7-38, 15-4, 15-5, 16-3, 16-4 Log() .................... 9-33, 9-34, 9-37, 9-38, 9-59, 9-62 - M - MAIN MENU ................ 1-5, 1-20, 1-23, 1-24, 1-28, 1-29, 1-31, 1-32, 1-33, 2-4, 2-6, 2-7, 2-11, 4-36, 6-4, 6-12, 6-13, 7-1, 7-3, 7-4, 7-5, 7-6, 7-7, 7-8, 7-9, 7-10, 7-11, 7-14, 7-30, 7-39, 7-41, 11-1, 16-3, 16-4 MBBSINIT ................. 1-7, 1-34, 2-2, 3-1, 3-2, 3-5, 4-40, 5-7, 5-8, 6-2, 6-3, 9-2, 9-3, 9-10, 9-59, 10-2, 16-2, 17-2, 17-3, 17-4, 17-5, 17-7 MESSAGE MENU ............. 1-28, 1-29, 1-31, 2-11, 4-34, 6-12, 6-13, 7-4, 7-11, 7-12, 7-13, 7-14, 7-15, 7-16, 7-17, 7-26 MILC_CMDS ................ 1-24, 4-1, 4-49, 4-50, 7-35, 15-10 MNP ...................... 1-14, 1-16, 1-36, 1-37, 7-21, 9-13 Magnum-to-Magnum ......... 5-15, 7-32, 15-1, 15-2, 15-3, 15-4, 15-5, 15-6, 15-7, 15-8, 15-9, 15-10 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Page I-4 Index Mail account ............. 15-4, 15-8, 17-1, 17-3, 17-6 Mailing Labels ........... 9-1, 9-33, 9-35 Marked files ............. 2-16, 7-18, 7-28 Marking .................. 7-14, 12-1 Message group ............ 9-7 - N - NotePad .................. 2-16, 6-21, 7-14, 12-1, 12-2, 15-4 NotePad Facility ......... 12-1, 12-2 - O - OUTSIDE MAIL ............. 1-23, 2-7, 4-32, 4-41, 7-11, 7-36, 9-8, 12-2, 16-1, 16-2, 16-3, 16-4, 17-1, 17-3, 17-4, 17-6 OUTSIDE MAIL ID .......... 4-32, 12-2, 16-3, 17-1 Offline .................. 2-14, 10-1, 11-1, 16-1, 16-2, 16-3 - P - PLAY ..................... 5-14, 16-2 POWER .................... 3-1, 4-18, 4-20, 4-26, 4-27, 4-34, 4-48, 9-23, 9-25, 9-59 PRTY ..................... 5-14 - Q - QWK ...................... 1-30, 2-5, 2-6, 2-7, 11-1, 16-1, 16-2, 16-3, 18-5 - R - RJE ...................... 1-17, 1-24, 1-28, 1-31, 1-32, 2-2, 2-4, 2-6, 2-10, 2-14, 2-15, 4-8, 4-12, 4-13, 4-14, 4-31, 4-40, 4-42, 4-43, 6-2, 6-8, 6-12, 6-13, 6-17, 7-2, 7-4, 7-8, 7-10, 7-17, 7-28, 7-39, 7-40, 7-41, 7-42, 9-1, 9-3, 9-5, 9-7, 9-8, 9-12, 9-13, 9-14, 9-22, 9-28, 9-59, 11-1, 13-3, 16-1, 16-2, 16-3, 18-3, 18-4 RMAIL .................... 1-22, 5-15, 7-36, 15-1, 15-2, 15-3, 15-4, 15-6, 15-7, 15-8, 15-9 RTS ...................... 1-1 Redirected serial port ... 1-11 Refresh .................. 4-17, 5-11 Remap .................... 2-3, 13-3 Remote Mail .............. 1-22, 2-4, 2-5, 4-41, 5-15, 6-4, 7-15, 7-36, 9-7, 12-2, 15-1, 15-2, 15-3, 15-4, 15-5, 15-6, 15-7, 15-8, 15-9, 15-10 Remote Snoop ............. 1-27, 7-38 Restore_data() ........... 4-50, 9-52 Return(x) ................ 9-47, 9-61, 9-63, 9-64 - S - SNOOP .................... 1-27, 1-33, 5-3, 7-38 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems Index Page I-5 SPECIAL .................. 1-10, 1-20, 1-36, 1-37, 1-38, 3-3, 7-6, 7-22, 7-25, 9-8, 9-16, 9-19, 9-20, 9-31, 9-64, 18-3 STARTUP .................. 1-1, 1-5, 1-6, 1-7, 1-8, 1-10, 1-12, 1-13, 1-14, 1-18, 1-19, 1-23, 1-24, 1-29, 1-30, 1-34, 1-35, 1-36, 1-37, 1-38, 2-2, 2-7, 3-1, 3-2, 3-3, 3-6, 4-1, 4-9, 4-40, 4-42, 4-43, 5-5, 5-8, 5-14, 5-15, 5-16, 5-19, 5-23, 6-2, 6-3, 6-8, 6-9, 6-14, 7-3, 7-4, 7-7, 7-9, 7-16, 7-19, 7-26, 7-40, 7-42, 8-1, 8-3, 9-7, 9-13, 9-51, 9-52, 9-65, 11-1, 13-1, 13-2, 13-3, 15-10, 16-2, 16-3, 17-1, 17-2, 17-4, 17-5 SWITCH ................... 1-4, 1-5, 1-6, 5-3, 5-4, 5-5, 5-17, 7-5, 7-7, 7-9, 7-20, 7-38, 7-40, 9-7 SYSOP MENU ............... 1-5, 1-10, 1-28, 1-31, 1-33, 2-7, 5-6, 6-4, 6-12, 6-13, 7-1, 7-9, 7-18, 7-29, 7-30, 7-31, 7-32, 7-33, 7-34, 7-35, 7-36, 7-37, 7-38, 7-39, 7-40, 9-28, 10-2, 14-1, 14-2, 15-5, 16-1, 16-3, 16-4, 17-1, 17-2 Save_data() .............. 4-50, 9-52 Security Level ........... 1-19, 1-25, 1-26, 1-29, 1-31, 2-4, 2-17, 4-23, 4-39, 5-6, 6-9, 6-12, 6-13, 7-4, 7-6, 7-9, 7-19, 7-30, 7-34, 7-35, 9-1, 9-6, 9-13, 9-18, 9-22, 9-23, 9-56, 14-1, 14-2, 17-1, 17-2, 17-4 Server ................... 1-3, 1-9, 1-11, 10-3, 13-2, 13-3 Shutdown ................. 5-1, 5-4, 5-9, 5-10, 7-38, 8-4, 8-6, 17-4 Slog() ................... 9-29, 9-37, 9-38, 9-62 Sysbell .................. 5-12 System() ................. 9-29, 9-50, 9-52, 9-63 - T - TIME+NNN ................. 5-7 - U - UUCP ..................... 17-1, 17-5 Uudecode ................. 17-6, 17-7 Uuencode ................. 17-6, 17-8 - W - While() .................. 9-29, 9-40, 9-60, 9-62 While() { ................ 9-62 Workstation .............. 1-3, 13-1, 13-2, 13-3 - Y - Ymodem ................... 7-21 Ymodem-G ................. 1-9, 7-18, 7-21 - Z - ZIP Compression Format ... 18-5 Zmodem ................... 2-7, 7-21, 16-4 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1996 Gilmore Systems This Page Intentionally Blank